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INTRODUCTION 


FORTH was the brain child of a man called Charles Moore. After trying 
out various aspects of the concept for some years, he began to fit them 
together towards the end of the nineteen-sixties, though it was some time 
before a completely coherent version emerged. Seeing his invention as a 
‘fourth generation’ computer language, but restricted by his equipment to 
five-letter names, he chose to drop the ‘u’ and call his concept ‘FORTH’. 

Since then, the language has developed in various directions, the two 
mainstream versions being FORTH79 and fig-FORTH. The ‘fig’ prefix 
refers to the FORTH Interest Group, of San Carlos, California, who have 
endeavoured to make the language accessible to as wide a range of 
users as possible. | 

That range now extends to users of a number of microcomputers, but 
each implementation is slightly different from the others, the original 
definition of fig-FORTH allowing ample scope for individual choice of 
facilities. This book is specifically based on Spectrum FORTH by 
Abersoft, which is perhaps the most complete and user-friendly version 
available. Much of what is said will be equally applicable to other versions 
of fig-FORTH, and where the other versions omit some of the words 
described it will be possible to extend them to match the Abersoft 
standard, though some facilities may be more difficult to provide. 

FORTH79 is a different matter. It uses different words, and gives some 
words different meanings. And while the basic concept is much the same 
as that of fig-FORTH the implementation is quite different. However, 
flexibility is an inherent characteristic of both types of FORTH, and this 
may allow some of the discrepancies to be smoothed out by the provision 
of new words and revised definitions. 

A major problem facing newcomers to FORTH is the size of the 
‘vocabulary’, which is the list of predefined words. This is usually 
tabulated in the order of the ASCII code representation of the words, but 
when the vocabulary is displayed in response to the command VLIST 
(followed by return) the words are in a completely different order. In either 
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case, finding the right word to do a particular job is not easy. The 
approach adopted here is to group the most frequently used words 
according to the kind of action which they cail up, so that a given kind of 
function can be located quickly. In addition, Appendix A provides a full 
definition of the standard words in the form of a compressed summary of 
the ‘dictionary’, the area of store in which the words are defined. 

Nevertheless, it would be wrong to expect to be able to start writing 
FORTH programs immediately. The best approach is to learn the 
operative words in groups, experimenting with them while you get the 
feel of the system. Then you can start defining new words of your own 
with greater confidence, and later begin to define complete programs. 

This progressive approach is possible because FORTH can be used 
at different levels. It will interpret existing single words or a series of 
words in ‘direct’ mode, which may be compared with direct mode in 
BASIC. On the other hand, it will compile new words, creating new 
dictionary entries for them, and these words can thereafter be used in 
compiling further definitions. Ultimately, a single word will call up a 
complete program. 

The dictionary entries are formed in such a way that the routine 
associated with each word can be found very quickly. Whereas a BASIC 
interpreter has to scan through link tables to find the required entry point, 
FORTH stores the entry point directly, and no scanning is required. This 
makes FORTH a good deal faster than BASIC, which is perhaps its 
principal asset. Another asset is economy of store usage. 

To enjoy these advantages, you must be prepared to help the 
language along, by doing things that would be done for you automatically 
if you were using BASIC. You must think a little more, keeping a watchful 
eye on what the program is doing. In return, FORTH will give you a 
flexibility limited only by the scope of your imagination. 


Getting Started 


The Abersoft tape takes about 70 seconds to load; and this header 
should appear on the screen; 


48K SPECTRUM fig-FORTH (version) 
(Cc) Abersoft: 1983 


This tells you that your Spectrum has become a FORTH machine. 

The first sign of the change is that the flashing cursor shows a letter ‘C’, 
rather than ‘L’. As most of the standard FORTH words are in upper case 
lettering, it is more convenient to work in ‘capitals mode’, though you can 
always select ‘L’ mode in the usual way, using CAPS SHIFT and 2. 

You will notice that the little beep indicating key depression has 
disappeared. If it returns, you have dropped out of FORTH into BASIC, 
for some reason, but you can return to FORTH by GOTOS. You can get 
into BASIC deliberately by typing MON and ENTER, but you will find that 
only direct execution is possible, as there is no room to add to the short 
BASIC program already established. 
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The keys will no longer produce BASIC words, which are not needed 
by FORTH. You will have to type everything letter by letter. There is no 
Extended Mode, but you will find that some symbols normally obtained in 
that mode, plus a few new ones, can be produced by using SYMBOL 
SHIFT and certain other keys, e.g: 


Key ‘Y’ gives [ 
} 


Key ‘U' gives 

Key ‘A’ gives ~ 
Key ‘S’ gives | 
Key ‘D’ gives 
Key 'F’ gives t 
Key ‘G’ gives } 


Graphics are accessible in the usual way. 

Once you get out of the habit of using key ‘K’ for LIST, which is a 
FORTH word, you will find no serious problems. 

A number of familiar functions are retained, as detailed in the section 
on ‘Spectrum Specials’, but you will find that they are not quite the same 
as the BASIC forms. For example, the parameters must come before the 
comman4d, not after. 

An important difference concerns BREAK. In some circumstances, 
pressing CAPS SHIFT and SPACE together will still stop a program, but 
an alternative is provided by CAPS SHIFT and 1. This, however, will only 
work if you have written your program to respond to this input. If you 
make no provision for BREAK, you may find that the program is stuck in 
an infinite loop, with no way out. Details of the way to avoid this are given 
in the section on branching and looping, but you should have no need to 
worry about them for the time being. 

lf you decide to take a different kind of break, by loading another sort of 
program, you will need to reset RAMTOP, otherwise you will get an Out 
of Memory report. The easiest procedure is to switch the computer off 
and on again, so that the usual parameters are initialised. 

lf you are interested in such matters, the initial area occupied by the 
FORTH program after loading is 5E06 to 8159, with reserved workspace 
from CB40 upwards. The intervening space is available for your FORTH 
words, which take the form of extensions of the ‘dictionary’ that is the 
fundamental definition of FORTH. The dictionary grows upwards, and 
the calculation stack grows downwards. If you want to know how much 
space is left between them, input: 


FREE . ENTER 
This will display the number of free bytes. 
A ZX Printer will work with FORTH. Switch it on by: 
1 LINK ENTER 
Switch it off by: 
O LINK ENTER 


Because FORTH is different in a number of ways from most other 
languages, the next section will examine its general characteristics. If 
you already know what they are, you can skip forward with confidence. 


The Essentials of FORTH 


Used in direct mode, FORTH works like a calculator operating in 
Reverse Polish Notation. The data which you key in is shown on the 
screen and stored in an 80-character input buffer, which will hold 2’ 
lines of displayed data. When the buffer is full, or if you press ENTER to 
indicate that an input is complete, the system begins to scan the buffer, 
stopping at the first space character which it finds. The data which has 
been scanned is then compared with the list of words in the dictionary, 
which can be seen by: 


VLIST ENTER 


You can stop the listing by pressing BREAK (CAPS SHIFT/1), as the 
full list occupies more than the screen area. 

lf the data matches a defined FORTH word, the action associated with 
that word is performed. Otherwise, the data is checked to see if it is a 
valid number. If it is, the number is stored on the calculation stack. If it is 
neither a FORTH word nor a number, error report 0 is displayed, with the 
offending word. 

Because Reverse Polish Notation is used, with data stored on a 
‘stack’, the FORTH words act on the last numbers to be input. Try this 
input: 

45 * 

Leave a space between each element of the input, remembering that 
“space” is the standard “delimiter” marking the start and end of each 
word or number. The response will be to display the number 20. The way 
this works is that FORTH takes the data up to the first space, in this case 
the number 4. Because it is a number and not a FORTH word it is stored 
on the stack. The procedure is repeated for the number 5, and this is 
stored on the stack on top of 4 . Then FORTH comes across the “*”. 
Because it is a FORTH word and we are in direct mode it is executed. 
FORTH takes the last number (5) from the stack and the next one down 
(4) and multiplies them together, putting the result back on the stack. The 
next FORTH word in the buffer is the dot “.” This displays the result. 

lf we expand on the above and input the following: 

45* 23+. 


Up to the “*” everything is the same as above with the result 20 on the 
stack. FORTH continues to read the line and stores 23 on the stack on 
top of 20, and goes on to read the next word. This (+) is a FORTH word 
and it adds the top two numbers on the stack, 23 and 20, and stores the 
result, 43, back on the stack. The ‘dot’ once again displays the result. 
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The action of the FORTH words in these inputs has been explained in 
a relatively simple manner that should suffice for the moment, but it will 
be evident that exact definitions are needed, and these will be supplied 
later on. 

There is no need to enter a complete set of numbers and words on one 
line. Each could go on a separate line, followed by ENTER, since the 
input system deals with only one element at a time. If you enter too many 
characters, overfilling the buffer, you will probably get an error message, 
because the last word entered may not be complete, but the earlier 
elements of the line will be processed normally, and as the error report 
identifies the word to which it refers you will know where to continue the 
entry. 

Not all the words displayed by VLIST can be used in direct mode, and 
an attempt to use them will produce error 17. These words can only be 
used in compiling mode, which sets up new dictionary entries defining 
fresh FORTH words. 

Here is an example: 


- TEST1 “ + . 

The colon instructs the system that all input words and numbers up to 
the subsequent semicolon are to be compiled, the result being identified 
with the word name TEST 1. 

Now input the following: 


23 4 5 TEST1 


The result is 43, as in the earlier example. TEST1 performs the 
multiplication, the addition, and the display function which we previously 
input as separate words. It would be a good idea to simulate the stack on 
paper to ensure you get your values and operators in the correct order. If 
you do this for the above you will see why 23 comes first. 

You couid define another word: 

"TEST2 23 4 5 TEST1, 


An input of TEST 2 would display 43. That would be rather pointless, 
but it illustrates how a FORTH hierarchy is built up. In the end, acomplete 
program is called by input of a single word. That word defines a list of 
other words to be executed in turn, and some or all of the words in the list 
may define further lists. 

It is interesting to compare this with the action of BASIC, which uses 
numbered lines containing statements which specify the action to be 
taken. The numbering is used to indicate the required order in which the 
Statements are to be executed. A well-structured BASIC program, 
however, can be seen as a number of functional blocks, each composed 
of a number of lines, though some programs cram so many statements 
into a line that a single line may represent a block. This makes the 
program difficult to interpret from the listing. 
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FORTH, on the other hand, gives each functional block a name, and 
that name is linked with a name list defining the functions to be carried out 
by the block. Groups of blocks are similarly linked by further names and 
lists, until a single name and list brings all the groups together in a single 
program called by a single name. 

Clearly, this is not a process which can be approached too casually. 
Because a BASIC program can be modified by editing, it is sometimes 
possible to create a fairly simple routine as you go, correcting errors as 
they become obvious. With FORTH, it is advisable to plan ahead, 
deciding on the content of each functional block in advance. This can 
impose an irksome discipline if you prefer the more casual approach 
permitted by BASIC, but the speed of execution of the result makes the 
effort worthwhile. 

An important problem for anyone approaching FORTH for the first time 
is the sheer number of words which are available for use. The only 
solution is to learn the vocabulary in sections, gradually expanding your 
understanding of the range of actions which you can handle. That is the 
basis on which the remainder of this book is planned. If the detailed 
explanations of some words seem too complex, leave them and come 
back later, accepting that the words act as described. You will find that 
you can very soon begin to understand what is happening, even in the 
most complex functions. 

Another problem for newcomers to computing stems from the fact that 
all numeric data Is stored in binary form. Not so many years ago, binary 
was considered incomprehensible for anyone but a computer expert. 
After a lecture on the subject, a man got up, scrawled a series of ones 
and noughts on the blackboard, saying that no one could make sense of 
that. As he put in the last nought, a small voice from the audience said 
‘three hundred and eighty four’. The man stared, and laboriously 
checked the value of his ‘incomprehensible’ binary number, to find the 
translation was correct. The small boy who had made the translation 
looked surprised, and explained that all he had done was to take the first 
digit, and when another digit was added he doubled what he had and 
added the new digit. For example: 


ant, 
nO Wd — 


48 
96 
192 
384 


oo oo o00 =—- + 
NO 
Ba 


The number on the blackboard was 110000000, not the most difficult 
of numbers to translate, but the principle is useful to remember; and it 
applies to any number base. 


For example, in base 3, the number 112020 translates thus: 


1 1 
1 4 
2 14 
0 42 
2 128 
0 384 


FORTH performs this process for any number base you like to select, 
not only for input, but also for output. This can lead to confusion if you fail 
to appreciate what is happening, so the study of the vocabulary will begin 
by looking at the way numbers are input, stored, and output. 


PARTI: 
Direct Mode 


This part deals with FORTH words which can be input for immediate 
execution. Some versions of BASIC can be used in this way, in what is 
then called ‘direct’ or ‘calculator’ mode. In a later section the use of 
compiling to create new words will be examined, and that will prove more 
convenient for complex operations, but though it can be slow and tedious 
to work in direct mode it gives a better insight into exactly what is 
happening. 


NUMBER REPRESENTATION 


The key to the operation of FORTH is the ‘stack’. For those who are 
unfamiliar with the term, a stack is the ‘last-in-first-out’ buffer store which 
can be compared with the old-fashioned filing spike. If you put bills on to 
the spike as they arrive, the first to come off will be the one which was put 
on last. FORTH uses two stacks, one for calculation and the other for 
holding link addresses. They will be called the Calculator Stack (or often 
just Stack by itself) and the Return Stack, respectively. 

In Spectrum FORTH, the Z80 stack is used for the Calculator Stack. 
The 280 stack handles data in the form of 16-bit words, even where 
nothing more than a single ASCII code is involved. That suits FORTH 
perfectly. Computers using other processors may have stacks that hold 
8-bit words, but they have to store two such words for each transfer to the 
stack. In general, except for some specialised functions, FORTH is 
unaltered by machine characteristics. 

Another point is that FORTH recognises no distinction between data 
types, which can have disconcerting consequences on occasion. The 
meaning of data words depends on the way they are treated. For 
example, type 40000 followed by ENTER. Then type a “dot” (full stop), 
again followed by ENTER. The dot displays the number from the top of 
the stack, which is of course the last number stored there. The number 
displayed is —25536 and not 40000. Where did that come from? 
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Signed and Unsigned Numbers 


A 16-bit binary number can have 65536 different values. In ‘pure binary’, 
these values range from 0 to 65535, bit n having the value 2", where the 
least significant bit is bit 0. If, on the other hand, we adopt ‘2’s 
complement’ representation, the value allocated to the most significant 
bit is -2" instead of 2". The rest of the bits can represent values from 0 
to 32767. If bit 15 is 0, that is the range of the complete number. If bit 15 is 
1, then 32768 (2"°) is subtracted, making the range —32768 to — 1. Since 
the number is always positive when bit 15 = 0 and negative when bit 
15 = 1, the bit is commonly called the ‘sign’ bit. 

A mild word of warning is needed here regarding the number —32768. 
It behaves a little oddly, being unchanged by negation. In this respect, it 
can be compared with zero. It is best avoided, the working range being 
taken as + 32767. | 

FORTH allows you to choose between pure binary and 2’s 
complement representation at will. The simple ‘dot’ (as the full stop 
character is known in FORTH circles), will display a number on the basis 
that it is in 2’s complement form, while U. will assume that the number 
is in pure binary. Since the number 40000 is outside the 2’s complement 
range, it was stored as pure binary. Using dot to display it gave the 
interpretation of 2’s complement. Both 40000 and -—25536 are 
represented by the binary number 1001110001000000. Note that they 
add up to 65536. 


Double Numbers 


The value range for 16-bit numbers is rather limited, so FORTH provides 
for the use of 32-bit numbers, which are held as two successive stack 
items, the upper 16 bits being nearest to the top of the stack. 
4,294,867 ,206 different values can be represented, and 2’s complement 
representation is usual, giving a range of +2,147,483,647. The 
anomalous number in this.case is —2, 147,483,648. 

You can enter a double number from the keyboard by including a 
decimal point somewhere in the number. The position of the point is not 
directly relevant, but the number of digits to the right of it is noted in the 
variable DPL for possible future reference. 

A point to watch is that a number outside the +32767 range, entered 
without a decimal point, can cause problems. The input routine always 
interprets a numeric input as a double number, but if there is no decimal 
point the upper half of the result is thrown away. This can cause some 
mystifying results on occasion. 

A double number can be displayed by the word D. , which assumes 
that the number is double and in 2’s complement form. 


Number Base 


By default, FORTH accepts input numbers and generates output 
numbers on the basis that decimal notation is intended, converting the 
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numbers to and from the internal binary representation. If so instructed, 
however, it will work in any number base you desire, within reason. The 
word HEX will call up hexadecimal notation, the word DECIMAL will 
restore decimal working. That, however, is only the beginning. 

The word ! instructs FORTH to store a number on the second stack 
position in a location defined by the top of stack. The 
phrase n BASE ! will therefore store the number n in the variable 
BASE, which determines the number base to be used in input and output. 
HEX is equivalent to 16 BASE ! , and DECIMAL is equivalent to 
10 BASE ! , while binary working is obtained by 2 BASE ! . These 
statements assume that decimal working is effective. If binary has been 
selected, 10 BASE ! would do nothing, since in binary 10 has the value 
two! You need 1010 BASE ! . 

For a digit value greater than 9, the letters A-Z provide a means of 
extending the digit range, so it would be possible to work in base 35. 
Beyond that some odd characters get into the act. 

The word @ instructs FORTH to obtain the contents of the location 
defined by the top of stack and put the result on the stack, so you might 
think that the current base could be determined by BASE @.__, but the 
result is always 10. Can you see why? There is a hint above. 

When using hexadecimal, the unsigned ‘pure binary’ convention is to 
be preferred, as negative hexadecimal numbers are confusing. 


Formatted Numbers 


One of the virtues of FORTH is an ability to display numbers in a very 
precise format. The simplest examples involve the words .R for single 
signed numbers, D.R for double numbers, and U.R for unsigned 
single numbers. 

These words take the number on top of the stack as defining a ‘field’ of 
that number of character positions. The next number on the stack is 
displayed in the right hand end of the field. Whereas a normal numeric 
Output adds a space after the number, these functions do not. It is 
therefore relatively easy to build up neat tabulations with the numbers 
‘right justified’, that is with their right-hand digits in a vertical line. Other 
facilities of this kind will emerge in due course. 

Meanwhile, we have made a start by defining ten FORTH words and 
phrases. 

For convenience, they may be summarised as follows: 


TOS means ‘top of stack’, 20S means ‘second on stack’ and so on. 
Remove TOS and display it as a signed single 


number. 

U. Remove TOS and display it as an unsigned single 
number. 

D. Remove TOS,2OS and display as a signed double 


number. 
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n BASE ! Setbasennotation 
HEX Set hexadecimal notation 
DECIMAL Set decimal notation 
BASE @ . Read current base 


-R Remove TOS,20S. Display 20S as a single signed 
number at the right hand end of a field of TOS 
characters. 

U.R Remove TOS,20S. Display 20S as a single 
unsigned number at the right hand end of a field of 
TOS characters. 

D.R Remove TOS,20S,30S. Display 20S,30S as a 
double signed number at the right hand end of a field 
of TOS characters. 

ARITHMETIC PRIMITIVES 


The range of FORTH words is built up on a foundation of a number of 
blocks of machine code. Other words are created by combining or 
modifying these ‘primitives’, but the action of these other words can only 
be understood if the primitives are examined first. 

You may be surprised to find that there are only eight arithmetic 
primitives. Later, we will see that they form the basis for another 
seventeen derivatives. 

It is important to remember that FORTH words act on numbers or other 
data which is already on the stack. To add 7 and 8, we need: 

7 8 + 


Examining what is happening, we begin by typing the characters and 
spaces, which are stored in the Terminal Input Buffer. The INTERPRET 
routine takes the entries delimited by spaces in turn. It sees 7 as a valid 
number, having first considered it as a possible FORTH word, and the 
numeral 7 goes on the stack. 8 is treated similarly, and it also goes onto 
the stack. The numeral 8 is ‘TOS’ and the numeral 7 ‘20S’. The pilus sign, 
however, is recognised as a FORTH word, and it is executed. It takes the 
two top stack items, adds them together, and puts the result back on to 
the stack. We could now display the result by using ‘dot’ or ‘Udot’. 

incidentally, there is no need to input all three characters on the same 
line. The effect would be the same if we input: 

7 
8 


+ 


This is because FORTH operates on each word or number in turn. 
Pressing ENTER merely invites INTERPRET to examine what has been 
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put in the Terminal Input Buffer (TIB for short). If you want to know where 
the TIB is held, HEX TIB @ U. will tell you. All part of the FORTH 
service! 

A minus sign is also a FORTH word. It removes the two top items from 
the stack, subtracts TOS from 20S, and puts the result back as TOS. 

This kind of calculation is known as Reverse Polish Notation, and as it 
has been used in some calculators it may not be completely unfamiliar. It 
avoids ambiguity, since the operators act in a clearly defined way on 
clearly defined numbers. Where normal arithmetic notation needs 
brackets and priority rules to determine its interpretation, Reverse Polish 
leaves no room for doubt. 

On the other hand, it does require that the right numbers are in a 
position to be operated on at the right time, and this can call for some 
careful thought and advance planning. A browse through the dictionary 
definitions in Appendix A will reveal some interesting examples. 

The next ‘primitive’ is U*, which takes away TOS and 20S and puts 
their product on the stack as a double number. Then we have U/MOD , 
which takes away the three top stack items, treating the second and third 
as a double number to be divided by the first item. The remainder is put 
on the stack as a single number, and the quotient, again as a single 
number, is put on top of it. 

Putting the remainder on the stack may seem pointless, but it is there 
for a very good reason. Suppose you have a double number on the stack 
representing a number of seconds. Adding 60 U/MOD wiil divide the 
number by 60, and the quotient will give the number of minutes, the 
remainder the number of remaining seconds. Try: 

200. 60 U/MOD .. 


The decimal point after 200 is needed to set it up as a double number 
for U/MOD to work on. We can use ‘dot’ for the output, because the result 
will be less than 32767, and there will be no confusion over sign. Now try: 

36484. 60 U/MOD 0 60 U/MOD ... 


The zero entry is needed to make the single word result of the first 
U/MOD into a double word for the second U/MOD to work on. The three 
figures represent hours, minutes and seconds. 

This could be regarded as a calculation to base 60, and the routine for 
decimal output works on a similar sort of basis to that shown above, 
except that 60 is replaced by 10. 

There are times when a single number needs to be converted to a 
double number form, perhaps to allow U/MOD or a similar operator to be 
used. If U/MOD is applied to a single number, it will pick up whatever 
happens to be next on the stack and work on that. Once again, there can 
be strange results. 

If the single number is unsigned, we can extend it by putting a zero on 
the stack to form the upper half of the double number. If the single 
number is signed, and we want to preserve the sign, we must use 
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S—>D, which puts a zero on the stack if the single number is positive, or 
FFFFH if the single number is negative. This is called ‘propagating the 
sign bit’. 

To add two double numbers together, D+ is required. It removes four 
items from the stack, treating them as two double numbers, adds them 
together and puts the result on the stack as a double number. 

The last two primitives perform negation, MINUS acting for single 
numbers and DMINUS for double numbers. The action is to subtract the 
number from Zero. To all intents and purposes, the number seems to stay 
in its place on the stack, though in fact it is removed and then put back. 

These eight primitives may seem rather inadequate, but before we 
examine the seventeen derivatives we need to consider the stack 
manipulation operators, without which FORTH would be very restricted 
indeed. 


The operators described in this section may be summarised: 


+ Remove TOS,20S. Place their sum on the stack. 

— Remove TOS,20S. Place 20S-TOS on the stack. 

U* Remove TOS,20OS. Place their product on the stack 
as a double number. 


U/MOD Remove TOS,20S,30S. Treating 20S,30S as a 
double number, divide it by TOS. Place the 
remainder on the stack, then the quotient. All 
numbers are treated as unsigned. 


D+ Remove TOS,20S,30S,40S. Treating them as two 
double numbers, put their double number sum on the 
stack. 


S—>D Sign-extend a single number to form a double 
number. The original number becomes 20S, the 
extension TOS. 


MINUS Negate a single number on TOS. 
DMINUS Negate a double number on TOS,20S. 


STACK MANIPULATORS 


It will be evident that mathematical and other operations will call for a 
certain amount of stack shuffling in order to bring the required data to the 
right position. This is relatively easy when the number of items on the 
Stack is small, but a routine whch will be described later on involves up to 
72 items on the stack at the same time, and that is a more difficult 
proposition. 

One of the hardest-worked words in FORTH is DUP, which duplicates 
the TOS by adding a copy of the original TOS. This is essential when the 
value of TOS is being checked, as the check would destroy the number if 
it were not duplicated. A variant is —DUP, which only duplicates if TOS is 
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non-zero. This is useful where TOS is no longer needed when it reaches 
zero. There is also 2DUP, which duplicates TOS and 2OS. This is useful 
for duplicating double numbers, but it can also be used with single 
numbers. Suppose we want to calculate (4 + 3)*3 + 4. We can use: 


Stack 
43 4 3 
2DUP 43 4 3 
+ 43 7 
U* 421 0 
DROP 4 21 
+ 25 


U* generates a double number, so we discard the upper 16-bit entry by 
DROP, which discards TOS. 2DROP discards TOS and 20S. 

Next we have SWAP, which interchanges TOS and 20S, and 2SWAP 
which interchanges TOS/20S with 30S/40S. 

OVER is very useful. It adds a new TOS which is a copy of the previous 
20S. 2OVER adds a new TOS and 20S which are copies of the 
previous 30S and 408. 

Finally, in this group, ROT rotates the top three stack items, bringing 
30S to TOS, 20S and TOS to 20S. 


When you begin to write full-scale programs, you will find that it is very 
useful — if not essential — to write down tables like the one above, so 
that you can keep track of the stack movements. 

By so doing, you will soon realise that there is no way to ring the 
changes to bring deeply-buried items to the top of the stack, but you will 
find that this problem is eased when we come to the process of compiling 
new word definitions. 

Because of this limitation, it is often convenient to introduce some 
numbers in the course of a computation. These may be included in the 
input stream, or they may — as will appear in due course — be called up 
from constants of variables. Since that uses extra storage space, it is 
regarded as uneconomical by FORTH purists, but there is no point in 
Striving too hard for perfection. 
lows manipulators which have been mentioned may be defined as 

ollows: 


Stack Before Stack After 
DUP a aa 
2DUP ab abab 
DROP a 
2DROP ab 
SWAP ab ba 
OVER ab aba 
2OVER abcd abcdab 
ROT abc bca 
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Remember that the top of the stack is the right-hand entry. Only the 
relevant entries are shown. There may be other items ‘behind’ these, i.e. 
deeper into the stack and to the left of those shown. These are unaltered 
by the manipulators. 


OTHER MANIPULATORS 


At this point, it is necessary to mention some stack and display 
manipulators which do not fall conveniently under other headings. 

First there are three which are not permissible in direct mode, but 
which are used in producing some of the arithmetic derivatives. 
Reference has been made in passing to the Return Stack. It is 
sometimes convenient to remove the top of the caiculator stack from 
immediate action, perhaps to allow access to items further down the 
stack. These words facilitate this by allowing the top of the calculator 
stack to be transferred to the Return stack on a temporary basis. 

>R removes TOS and transfers the data to TORS (Top of 


Return Stack). 
R> performs the opposite function. 
R copies the TORS to TOS, without altering TORS. 


These words must be used with care, the Return stack being restored 
to its original state before a definition is completed, or reference is made 
to the Return stack contents for other purposes, as in control of loops. (A 
slip of this sort occurred in the definition of 2Q0VER in early Abersoft 
tapes. If you find that HEX 7F4E @ U. gives 6173, you have the bug. It 
can be cured by HEX 6188 DUP 7F4E ! 7F50! ) 

The screen manipulators are fairly obvious. CR calls for newline, and 
CLS clears screen. SPACE outputs a space, while n SPACES outputs n 
spaces. 

In direct mode, .“ string” outputs the string of characters between the 
quote characters. It corresponds to the BASIC PRINT “XXXXxX”. 


MORE ARITHMETIC 


Armed with the stack manipulators, we can now find out how the extra 
seventeen operators are created. However, we must first take a brief 
look at the logic operators, which are also involved. 

AND takes TOS and 20S and compares them bit by bit. Where both 
have a given bit in a true state, the corresponding bit in the result is set 
true. Otherwise the bit is set false. The result is put on to the stack. 

OR works in a similar way, but puts a true bit in the result where either 
TOS or 20S have a true bit in that position. 
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XOR also works in a similar way, but puts a true bit into the result if the 
corresponding bits in TOS and 20S are different. An interesting use is to 
obtain a result with sign bit set if the signs of TOS and 2OS are different. 

Some of the derived arithmetic operators are quite simple. 1+ is 
equivalent to 1 + , and it adds 1 to TOS. Similarly, 2+ is equivalent to 
2 + ,andit adds 2 to TOS. 

Next, we have +—, which removes TOS and negates the new TOS if 
the original TOS was negative. This is implemented by calling MINUS if 
TOS was less than zero. The double number version is D+ —, which 
removes TOS and negates the double number in 20S,30S if TOS was 
negative. 

MIN and MAX come next. They remove TOS and 2OS and discard one 
or the other, restoring the survivor to TOS. MIN restores whichever was 
less, MAX restores whichever was greater. In both cases 2DUP creates 
copies of TOS and 2OS to use as a basis for comparison, and then drops 
one of the original entries. 

Finally, at the first derivation level, we have M/MOD, which resembles 
U/MOD , except that it leaves a double number result instead of a single 
number result. This is convenient when working with large numbers. The 
word is constructed as follows: 


Stack 
abc 
>R ab cto TORS 
0 abO make b a double number 
R abOc recover c 
U/MOD ade divide b by c quotient e. 
remainder d 
R< adec recover c, clear TORS 
SWAP adce 
>R adc eto TORS 
U/MOD fg a/d divided by c. quotient g. 
remainder f 
R> fge Recover e. TORS clear 


Two divisions are performed. The first is ‘scaled’ by a factor of 65536, 
because b is really the upper half of a double number. The quotient and 
remainder are similarly scaled, so it is possible to ‘concatenate’ a and d to 
form a valid double number, which is again divided by c. The two 
quotients g and e can then be ‘concatenated’ as a double number. 

At the second level of derivation, we have ABS and DABS. ABS is 
implemented by DUP +-— . TOS is duplicated, and the copy is 
removed. If it is negative, the original TOS is negated. Whatever 
happens, TOS emerges as positive, the absolute value being preserved. 
DABS similarly uses 2DUP D+— to perform the same process on a 
double number. 


1/7 


We now come to M/ and M* . M* generates a double number product 
of two signed single numbers. It is based on U* , with the additions 


needed to preserve signs. 

Stack 
ab 

2DUP abab 
XOR abc 
>R ab 
ABS ab 
SWAP ba 
ABS ba 
U* de 
R> dec 
D+— de 


C is positive if a and b are of 
the same sign 

cto TORS 

b made absolute 


a made absolute 

product 

c from TORS. TORS clear. 
negate d/e if c negative. 


The XOR function is used to set up a flag indicating the required sign of 
the result, and this is held on the return stack while the calculation is 


performed. 

M/ is a little more complicated: 
Stack 
abc 

OVER abcb 
>R abc 
>R ab 
DABS ab 

R abc 
ABS abc 
U/MOD de 
R> dec 
R decb 
XOR def 
+— de 
SWAP ed 
R> edb 
+— ed 
SWAP de 


bto TORS 

cto TORS 

double number a b made 
positive 

c copied from TORS 

and made positive. 

a/b divided by c. quotient 
e, remainder d. 

c from TORS. TORS = b 
b copied from TORS 

f positive if b and c have 
same sign. 

negate e if f negative 


b from TORS. TORS clear 
negate d if b negative. 
remainder d, quotient e. 


The numbers a/b and c, though not the copies of them on the return 
stack, are made positive, and U/MOD calculates the absolute values of 
remainder and quotient. The quotient is negated if the signs of b and c 
differ. The remainder is given the sign of b. 


At the next level we have simpler derivatives. */MOD combines 
multiplication and division. it removes three items from the stack, all as 
single numbers. 20S and 30S are multiplied together, and the double 
number product is divided by TOS. Signed numbers are assumed 
throughout. 


Stack 

abc 
>R ab cto TORS 
M* de double number product 
R> dec c from TORS. TORS clear 
M/ fg f remainder, g quotient. 


/MOD removes TOS and 20S. Treating them as single numbers, it 
divides 20S by TOS and puts the remainder, then the quotient, on the 
stack. In essence, it is M/ adapted to operate on a single number: 


Stack 
ab 
>R a b to TORS 
S—>D ac sign extend a to double 
number form 
R> acb b recovered from TORS. 
TORS clear 
M/ de a/c divided by b, remainder d, 
quotient e. 


Now, at last, we come to the simple multiplying operator * . It ts 
implemented by M* DROP, the upper half of the double number result 
being discarded. Similarly, the simple division operator / is implemented 
by /MODE SWAP DROP, which discards the remainder. 

Finally, we come to */ and MOD . The first is implemented by */MOD 
SWAP DROP , the remainder being discarded. The second is 
implemented by /MOD DROP , which removes the quotient. 

These operators have been examined in detail because the simple 
definitions can sometimes seem ambiguous, and also because the 
detailed definitions show how FORTH words can be built up, pyramid 
fashion, to perform complex actions. 

Because the compiled definitions give explicit link addresses for each 
function which they call, the required functions can be found very quickly, 
and even a complex pyramid structure of many layers can be executed 
rapidly, though only the ‘primitives’ actually perform the necessary work. 

In this section, we have examined: 


AND Remove TOS,20S. Put on the stack a 16-bit AND of 
the two words. 

OR As AND, but an OR function 

XOR As AND, but an exclusive OR function 

1+ Add 1 to TOS 


2+ 
+ — 
D+-— 


MIN 
MAX 
M/MOD 


ABS 
DABS 


M/ 


\i* 


*/MOD 


/MOD 


MOD 


Add 2 to TOS 


Remove TOS. If it is negative, negate new TOS 
Remove TOS,2OS. If original TOS is negative, 
negate new TOS/2O0S. 

Drop TOS or 20S, whichever is larger 

Drop TOS or 20S, whichever is smaller 

Remove TOS,20S,30S. Divide 20S/30S (as 
unsigned) by TOS. Put the remainder, then the 
quotient, on the stack as single signed numbers. 
Give TOS a positive sign if necessary, by negation 
Give TOS/2O0S a positive sign if necessary, by 
negation. 

Remove 1TO0S,20S,30S. Divide 20S/30$S (as 
signed) by TOS. Put the remainder on the stack as a 
single number with the sign of the dividend, then the 
quotient with the sign appropriate to the signs of 
dividend and divisor. 

Remove TOS,2OS. Put their product on the stack as 
a signed double number. 

Remove TOS,20S,30S. Multiply 20S by 30S to 
form a double number product. Divide this by TOS. 
All numbers are signed. Put the remainder, then the 
quotient, on the stack as signed numbers. 

Remove TOS,2O0S. Divide 2OS by TOS and put the 
remainder on the stack with the sign of the dividend, 
then the quotient as a single signed number. 
Remove TOS,2O0S. Treating them as single signed 
numbers, put their signed single number product on 
the stack. 

Remove TOS,20S. Divide 20S by TOS and put the 
quotient on the stack as a signed number. 

Remove TOS,20S,30S. Multiply 20S by 30S and 
divide the double number result by TOS. Put the 
quotient on the stack. 

Remove TOS,20OS. Divide 20S by TOS and put the 
remainder on the stack. 


MEMORY ACCESS 


Access to memory depends on seven primitives allowing access to 
bytes, words and double words. If these are used normally, their detailed 
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action is not important, but if they are used in special ways their 
implementation can become significant. The primitives are: 


C! 


C@ 


2@ 


Remove TOS,20S. TOS defines the address of a byte 
location. The lower byte of 2OS is set in that location. 


Remove TOS,208. TOS defines the address of the first of 
two consecutive byte locations. The lower byte of 2OS is 
stored in the first location, the upper byte in the second. 
These locations are not machine dependent. 


Remove TOS,20S,30S. TOS defines the address of the 
first of four consecutive byte locations. The lower byte of 
20S is stored in the first location, the upper byte in the 
second. The lower byte of 30S is stored in the third 
location, the upper byte in the fourth. These locations are 
not machine dependent. 


Remove TOS. TOS defines the address of a byte location, 
the contents of which are put on the stack. (Upper byte 0) 


Remove TOS. TOS defines the address of the first of two 
consecutive byte locations. A word is formed from the 
contents of the first location as the lower byte and the 
contents of the second location as the upper byte, and the 
word is put on the stack. 


Remove TOS. TOS defines the address of the first of four 
consecutive byte locations. Two words are put on the 
stack. The lower byte of the second word comes from the 
first location, the upper byte from the second. The lower 
byte of the first word (which becomes 20S) comes from the 
third location, the upper byte from the fourth. These 
locations are not machine dependent. 

Remove TOS,20S. TOS defines the address of the first of 
two byte locations. Preserving the conventions set up by ! 
and @ , the contents of 2OS are added to the contents of 
the two locations. 


? is not a primitive ( = @. ) but it fits conveniently here. It prints the 
contents of a location defined by TOS. 

These words may be used with explicit addresses, but it is usually 
more convenient to use a variable name. Some variables, such as 
BASE, are defined from the start. Others will be mentioned as they arise. 

Calling a variable name puts the asociated address on the stack, so 
n BASE ! will put the value n into the BASE variable, while BASE @ will 
put the contents of BASE on the stack. New variables are set up by: 


Y VARIABLE name 


This sets up a 16-bit location pair, the address of which will be put on 
the stack in response to name . The variable is given the initial value Y. 
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For example: 
10 VARIABLE PILE 


will set up a variable with an initial value of 10 (interpreted according to 
the current value of BASE) and the variable can be read by PILE @ or 
reset by PILE !. 
For double number variables, the format is: 
YY 2VARIABLE name 


Four bytes locations are reserved and set to the double number YY. 
There is no standard provision for setting up byte variables, but 
extended store areas can be set up by using ALLOT. When a new word is 
set up in the ‘dictionary’, the necessary entries are made by reference to 
a pointer DP . ALLOT moves the pointer forward, extending the space 
available. For example: 
X VARIABLE name 6 ALLOT 


will set up a two-byte variable, with the necessary arrangement for 
creating access to it. The dictionary pointer will then move forward six 
locations, which are thereby reserved for extensions of the variable data. 
The locations are not cleared. The eight bytes so reserved could be used 
for a four-word array which could be accessed by: 

nname SWAP DUP + + 


SWAP brings n to TOS , where it is doubled, the result being added to 
the address set up by name . The final result will be the address of the 
lower byte of the nth element of the array. Adding @ would read the 
contents of the element. It would be equally possible to use the reserved 
space to hold eight bytes, when the address of the nth byte would be 
obtained by: 

nname + 


The correct read and write words for the chosen memory size must 
always be used, this being an example of the way the flexibility of FORTH 
places demands on the user. 

Constants can also be established. These behave rather differently 
from variables, in that calling the constant name puts the value of the 
constant on the stack, not the address of the constant. Since there is no 
question of writing to constants, who needs to know where they are? The 
defining formats for single and double number constants are: 

X CONSTANT name 
XX 2CONSTANT name 

One use for a constant is to define an address outside FORTH. The 
Spectrum operating system defines three bytes called FRAMES, which 
count in fiftieths of a second to indicate time elapsed since switch-on, 
with provision for setting the overall contents of the locations to any 
desired value. The three bytes can be read in combination by: 

23672 @ 23674 C@ 
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This sets up a double number. 
Rather than relying on memory of the right addresses, it is possible to 
define the first address as a constant: 


23672 CONSTANT FRAMES 

The locations can then be read by: 
FRAMES DUP @ SWAP 2+ C@ 
The stack action is: 

FRAMES 23672 


DUP 23672 23672 
@ 23672 (23672) Contents of location 23672 
SWAP (23672) 23672 
2+ (23672) 23674 
C@ (23672) (23674) Contents of location 23674 


This leaves the double number on the stack which is the current value 
of the Spectrum system variable FRAMES. It can be displayed by using 
‘Ddot’. 


Note how the addresses disappear as they are used, leaving the 
required result unencumbered. 

Access to operating systems outside FORTH can provide useful 
extensions, but caution is necessary. In the case of the Spectrum 
FRAMES variable, for example, incorrect values can be read. The 
variable is updated every 20 mS, and after every 20 minutes 50.72 
seconds the lower two bytes reach 65535. At the next update, they revert 
to zero, and the third byte is incremented. If this happens to occur 
between the time the lower bytes are read and the time the upper byte is 
read, a major error will result. 

This can be checked by calling FRAMES2 again immediately, when 
the result should not differ from the previous result by more than one. 

However, while bearing this in mind, you may care to work out how to 
use M/MOD and U/MOD to display elapsed time in hours, minutes and 
seconds. 

In addition to the words used to access particular locations or groups of 
locations, there are words that deal with wider areas. 

FILL removes TOS, 20S and 30S. Starting at a location defined by 
30S, 20S bytes are filled with the code defined in the lower byte of TOS. 
For example, if a block of store has been defined by: 

O VARIABLE ARRAY n ALLOT 
the locations in the block can be set to zero by: 
ARRAY n 2+ OFILL 


ARRAY sets up the start address in 30S, 20S is set to n+2, the 
number of bytes (including the two set up by VARIABLE), and 0 defines 
the code to be set in each location. 
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ERASE is effectively 0 FILL , allowing the above to become: 
ARRAY n 2+ERASE 

Similarly, BLANKS is effectively 32 FILL and fills the area with ‘space’ 
codes. 

CMOVE takes away TOS as a count, 20S as a destination address, 
and 30S as a source address. It copies the number of bytes defined by 
TOS from an area running upwards from the source address into an area 
running up from the destination areas. it should not be used if the source 
and destination areas overlap, with source below destination, since the 
source would be corrupted before it was copied. 

TOGGLE may be included in this group of words. It removes TOS and 
20S, using 2OS to define a byte location. The contents of the location are 
XORed with the lower byte of TOS, changing the state of any bit which is 
true in TOS. Originally created to serve a specific purpose, TOGGLE can 
be useful in other contexts. 

In the Spectrum, for example: 

23697 2 TOGGLE 


will reverse bit 1 of PFLAG and switch OVER on and off. 
Summing up the words which have been discussed: 

C! Remove TOS,20OS. Store low byte of 20S 
at TOS 

! Remove TOS,20S. Store 20S at TOS 

2! Remove TOS,20S,30S. Store 20S/30S 
at TOS. 

C@ Remove TOS. Replace by contents of 
byte location TOS. 

@ Remove TOS. Replace by contents of 
word location TOS. 

2@ Remove TOS. Replace by contents of 
double word location TOS. 

? Remove TOS. Output the contents of 
word location TOS as a single signed 
number. 

X VARIABLE name. Set up a two-byte variable with contents 
X, with location address linked to name. 

XX 2VARIABLE name_ Set up a four-byte variable with contents 
XX, with location address linked to name. 


ALLOT Remove TOS. Reserve next TOS bytes in 
dictionary. 

X CONSTANT name _ Set up a constant with value X, linked to 
name. 


XX 2CONSTANT name Set up a double word constant with value 
value XX, linked to name. 


24 


FILL 


ERASE 
BLANKS 


CMOVE 


TOGGLE 


Remove TOS,20S,30S. Set the code in 
the lower byte of TOS in 20S locations 
starting at 30S. 

Remove TOS,20S. Set zero in TOS 
locations starting at 20S. 


Remove TOS,2OS. Set space codes in 
TOS locations starting at 20S. 


Remove TOS,20S8,30S. Copy TOS 
bytes from an area running upwards from 
30S to an area running upwards from 
20S. 

Remove TOS,20S. Modify the contents 
of byte location 20S by XORing with the 
lower byte of TOS. 


SPECTRUM SPECIALS 


In general, FORTH is independent of the machine in which it runs, apart 
from variations in the fundamental vocabulary, but there are usually 
some special features that are machine dependent. The functions 
described here are particular to the Abersoft FORTH, which also has a 
larger general vocabulary than some other implementations. 

First, there are the screen control and graphics facilities, which are 
very similar to those of Spectrum BASIC, except that the parameters 
precede the command instead of following it. For functions relating to 
character position, for example, the line is defined by 2OS, the column by 


TOS 
YX AT 
Y X ATTR 


Y X SCREEN 


X INK , 
X PAPER , 
X BORDER , 


sets print position at line Y column X 
puts on the stack the attribute byte for line Y 
column X. 


puts on the stack the ASCII code for the 
character at line Y column X, except where the 
character is user-defined. 

Colour setting is straightforward: 

where X = 0-9 

where X =0-9 

where x = 0-7 


The numbers have the same significance as in BASIC. 

BRIGHT , FLASH , INVERSE and GOVER are enabled by a non-zero 
TOS and disabled by a zero TOS. Thus 0 BRIGHT inhibits BRIGHT, 
while 1 BRIGHT enables it. GOVER is the BASIC OVER, renamed for 
obvious reasons, OVER having a dedicated meaning in FORTH. 
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For dot graphics, 2OS specifies the X coordinate and TOS the Y 
coordinate. For example, 20 100 PLOT is equivalent to the BASIC form 
PLOT 20,100. 

DRAW , however, works on an absolute basis, rather than relatively, a 
line being drawn to a specified position, whatever has gone before. 

POINT returns 1 or 0 on TOS according to the state of the specified 
point on the screen. 

A particular feature of the dot graphics commands is that no error 
report appears if they stray off the screen, but the plotting process 
continues with limited co-ordinate values, and if you allow an excessive 
excursion you may have to wait a long time for the trace to reappear. 

UDG puts the start address of the user-defined graphics area on the 
stack. 

Finally, there is BLEEP , which is significantly different from BEEP. 
TOS defines pitch, and 2OS defines duration, but while there is greater 
flexibility than is directly available in BASIC the system is more difficult to 
use. Precalculation is necessary to obtain musical scales, on the 
following basis: 

To generate a frequency of F Hz, TOS must be set to: 


TOS = (437500/F) — 30 
Looking in the opposite direction: 
F = 437500/(TOS + 30) 


The duration of the note is determined as a number of cycles, so 20S 
must be set to F x T , where T is the duration in seconds. 

A point to note is that if a very low frequency is selected, with a high 
duration, the system may appear to hang up, because the ‘BEEPER’ 
routine in BASIC goes on and on and on. . .; without the user being able 
to use BREAK. 

BREAK (caps shift and space) will work in some circumstances but an 
alternative is provided by CAPS SHIFT and 1. This, however, will only 
work if you have written your program to respond to it. If you make no 
provision for BREAK you may find your program stuck in an infinite loop. 

One other point worth mentioning is that the ZX printer can be used 
with FORTH. it is switched on by 1 LINK and 0 LINK switches it off. 


SUMMARY OF PART |! 


More than eighty FORTH words have now been defined, but another two 
hundred odd remain to be mentioned. However, many of these are 
‘system’ words, which you will not need to use directly. Before going 
further, it is as well to become familiar with the words already defined, by 
trying out various combinations and observing the results. 
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Now and then, you may see an error report. If you try to read from the 
stack when it is empty, you will See error 1. If you use a word which is not 
in the dictionary, error O will appear. After any error the system clears 
down ready for a fresh start. Other errors are unlikely to arise at this 
stage, unless you do something rather improbable. 

You will find that there is no need to enter all your commands at once. 
Your input data goes to the Terminal Input Buffer. When you press 
ENTER, or if you overfill the buffer, the INTERPRET function is called to 
work out what you have said. It will first try to match a group of characters 
delimited by spaces with the name of a dictionary entry, and if that fails it 
wiil try to interpret the group as a number which is valid in respect of the 
current value of BASE. If that also fails, it will put up error O. 

INTERPRET works on one word at a time, so if you press ENTER after 
each word or number the action will be the same. Now and then a 
complete sequence is desirable. 

If you want to clear the screen before a particular action, you need to 
put CLS in the string of words and numbers which will call the action. 
Don't forget that the system insists on tacking ‘ok’ on to the end of an 
output which completes a string of actions. You may want to put 00 AT 
near the end of the string to put the ‘ok’ away in the top left corner of the 
screen. 


lf you want to find out what is happening to the stack without losing any 
data, a useful trick is to use: 


ROT DUP . ROT DUP . ROT DUP . 


This will display 30S,20S and TOS, in that order, but will leave the 
stack unaltered. You should be able to work out why. 

What can we do with the words we have examined? Not a great deal, 
you may say. We can carry out some complex arithmetic, but it is all in 
integer form, and that may seem limiting. With a little patience, you will 
find that the limitation need not be serious. A scan through the DRAW 
routine listed in Appendix A will give you a hint of the possibilities in that 
direction. The changes in X and Y values are calculated in units of 
2:00001 52, by using the scaling principle. That will be examined in detail 
ater. 

In terms of exploring the possibilities of FORTH, we have as yet barely 
begun. As a prelude to further progress, we need to look at the way the 
dictionary works, and the way we can begin to create words of our own. 
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PART Il: 
The Dictionary 


This part describes the structure of the dictionary, and the way FORTH 
uses the dictionary to respond to commands. Those who are impatient to 
go further ahead may skip this section for the moment, but it will help to 
explain mechanisms involved in the functions to be described. 


THE DICTIONARY 


Loading the FORTH tape sets up an area of store as the FORTH 
Dictionary, which contains all the essentials of the system. During 
initialisation a number of variables are set up outside the dictionary area 
and stacks and buffers are established, but the dictionary remains the 
heart of the system. 

The name ‘dictionary’ is precisely appropriate, since it refers to a list of 
words and their definitions. When you input a FORTH word, the system 
searches the dictionary for it and executes the defined action. With at 
least 260 words to check, this takes time, which is only acceptable 
because the process of entering the word will have taken longer. A more 
rapid process is needed for executing a program. 

The definitions for some words are so complex that they amount to 
Small programs in themselves. The word M/ calls up fifteen other 
words, and some of these call up yet more words. To allow this to be done 
quickly, the definitions are set up in the form of link addresses to the 
definitions for the other words, so that a simple machine code routine can 
jump directly to the required area. As there is no need to search for any 
word other than the first, FORTH wastes no time in moving from one 
Process to another. That is why it is so fast. 

To make such a system work efficiently, the dictionary entries must be 
laid out with care. Each entry is built up from four ‘fields’. 

First, there is the Name field. This begins with a byte called the length 
byte, which — among other duties — gives the number of letters in the 
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name being defined. Since the maximum permitted length is 31 letters, it 
can be defined by bits 0 — 4 of the length byte. 

Bit 5 of the length byte is the ‘smudge’ bit. When this is true, the word 
will not be recognised as valid, though it will be listed as present if VLIST 
is called to display the dictionary contents. The bit is set while a new 
dictionary entry is being created, and cleared when creation is complete, 
so that incomplete definitions are marked as invalid. 

Bit 6 of the length byte is set to indicate ‘precedence’. This means that 
the word will always execute, even during the creation of a new dictionary 
entry, when the system is said to be in ‘compiling’ mode and is taking all 
the other words it finds as being part of the new definition. 

Bit 7 of the length byte is always set true. 

The word itself, in ASCII code, completes the Name Field, the code for 
the last letter having bit 7 set to mark the end of the word. 

While the dictionary is being searched, each definition has to be 
examined in turn. To simplify this, the Name Field is immediately 
followed by the Link Field, which contains the address of the next 
definition to be examined. The search begins with the most recent entry, 
which is at the top of the dictionary, and works back down the store, 
checking a name field, and picking up the link if no match is found. This 
uses a variable called HERE, which is set from the main dictionary 
pointer. 

The linking process is illustrated in Fig 1, from which it can be seen that 
the number of locations that have to be scanned is kept to an absolute 
minimum. 

When the required entry is found, the third field comes into play. This is 
the Code Field, and it contains a link to machine code which must be 
executed to implement the function. The code itself can be anywhere in 
the dictionary, but where it covers the complete execution of the function 
it usually follows immediately after the Code Field. In some circles, words 
which are entirely executed in machine code are called ‘primitives’, as 
they are the basic elements which perform the actual work, being called 
up in the required sequence by higher level words. 

Many words, however, are defined solely by reference to other words, 
and for these the Code Field links to a routine which interprets the fourth 
field, the Parameter Field. 

The Parameter Field contains a series of links to the Code Fields of 
other words, some of the links being followed by data necessary to the 
action of the other words. For example, there is a word LIT , which is an 
abbreviation of LITERAL. Its function is to put the data which comes next 
in the Parameter Field on to the stack. Similarly, the word .” is followed 
in the Parameter Field by text to be output. In this way, the Parameter 
Field constitutes a complete program definition for the word which it 
serves. 

some of the more mysterious FORTH words exist mainly to help the 
interpretation of the dictionary. TRAVERSE , for example, moves the 
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NAME FIELD n+1 
LINK FIELD n+1 
CODE FIELD n+1 
DEFINITION 
n+1 


PARAMETER FIELD n+1 
(or machine code) 


NAME FIELD n 
LINK FIELD n 
CODE FIELD n 
DEFINITION | 
n 


PARAMETER FIELD n 
(or machine code) 










FIG. 1: DICTIONARY FORMAT, SHOWING SCAN PATH 
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scanning pointer (temporarily held on 20S) from one end of the name 
field to the other. Taking TOS and 2OS from the stack, it adds TOS to 
20S repeatedly until a byte with bit 7 true is found. If TOS is 1, 
TRAVERSE scans forwards. If TOS is —1 , the scan is downwards. The 
resulting pointer value is left on TOS. 

TRAVERSE is usually called as part of a process. The word NFA, for 
example, converts TOS from the address of a Parameter Field to the 
address of the associated Name Field, and has the form: 


5 — —1 TRAVERSE 


Subtracting five from the Parameter Field Address takes TOS back 
past the Code Field and the Link Field, which contain two bytes each, to 
the end of the Name Field. The combination — 1 TRAVERSE then scans 
back to the start of the Name Fieid. 


PFA performs the reverse conversion, its form being: 
1 TRAVERSE 5 + 
The Name Field is scanned to the end, and the addition of 5 taking 
TOS to the Parameter Field Address. 
Adding a new dictionary entry is simple. If you input: 
23672 CONSTANT FRAMES 
: FRAME FRAMES DUP @ SWAP 2+ C@ ; 


you will find that you have created a new constant called FRAMES anda 
new word FRAME that can be used to put the contents of the Spectrum 
FRAMES variables on to the stack as a double word. 

The colon calls up compiling mode, so instead of executing the words 
which follow it the system sets up a new dictionary entry with the new 
FRAME , setting the Parameter Field to call us DUP @ SWAP 2+ C@ in 
sequence. (See Part Ill for more detail on colon definitions.) 

It is now possible to read the variable by calling the single word 
FRAME , instead of calling up each of the constituent functions in turn. If 
you wish, you can use the:word FRAME in a further definition, since it has 
exactly the same standing of the rest of the words in the dictionary. 

The semicolon terminates the process, returning the system to 
execution mode. 

To find the correct links for the parameter field entries, it is necessary 
to search through the dictionary for the relevant words, so compilation is 
relatively slow, but execution of the compiled word will be fast. Once you 
have defined a word, you can use it in defining others, and you will find 
that there are a number of standard words which can only be used in 
‘colon definitions’. 

An important point concerns the ‘smudge’ bit of the length byte in the 
name field. When the creation of the new entry begins, the bit is set to 
indicate an invalid definition, and it is not reset until definition is 
completed. If anything goes wrong, such as the discovery of a non- 
existent word in the definition, the bit is left set. The word can then be 
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found by VLIST , which lists the words in the dictionary, but it will not 
otherwise be recognised. 

Incidentally, the smudge bit is manipulated by SMUDGE, which is 
defined as LATEST 32 TOGGLE. LATEST leaves the address of the 
most recently created name field, and 32 (= 20H) selects bit 5 as the one 
to be ‘toggled’. 

Having defined FRAME, you may like to use it in further definitions: 


>: MINSEC 50 M/MOD ROT DROP 60 U/MOD 0 60 U/MOD... ; 
: CLOCK FRAME MINSEC ; 


Taking the second definition first, it calls FRAME , then MINSEC . 
FRAME puts the contents of the FRAMES variable on the stack as a 
double number, and MINSEC first divides the number by 50 to give the 
number of seconds since switch-on. The unwanted remainder is 
discarded by ROT DROP , and 60 U/MOD then separates the minutes 
and seconds. As this produces a single number result, 0 is added to the 
stack to form a double number, and a further 60 U/MOD will generate the 
hours and minutes as separate numbers. The three figures obtained are 
output in turn. 

Calling the single word CLOCK will therefore output the elapsed time 
since switch-on in hours, minutes and seconds. If you feel ambitious, you 
may like to try to define a word that will set the contents of the FRAMES 
variable in the BASIC area to give real time. 

If this examination of the dictionary format has whetted your curiosity, 
you may like to browse through the summary of the standard dictionary in 
Appendix A, which gives the definitions of all the standard words. You will 
find that a variable is entered in much the same way as an executive 
word, with a special routine to interpret the parameter field, while a 
constant is again similar in format but again uses a special routine. 

Because a single variable takes up at least eight bytes of dictionary 
space, it is understandable that the ideal approach is to minimise the use 
of variables. However, with ample space available it is permissible to be 
a little extravagant. 

This excursion into the mechanism of FORTH was not an essential 
factor in using the language, but it should have given a useful insight into 
what goes on inside the system. When all the available words are 
understood, it will be seen that the foregoing description has been very 
much simplified. Instead of relying on existing words to form a new 
definition, it is possible to enter machine code routines to execute special 
tasks. The process of compiling can be halted to allow the system to 
Caiculate data for further compilation, then compiling can be resumed. 

To make the most of the system, it is best to limit the size of each 
Created definition, rather than attempt to cram everything into a single 
definition. That way, the validity of each new word can be tested before 
going further, and overall confusion can be avoided. 

Mention of testing naturally leads on to the question of how errors can 
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be corrected. This will be dealt with in detail at a later stage, but it will 
suffice for the moment to say that it is always possible to FORGET a 
defined word. If it is the word most recently defined, that word alone will 
be erased from the dictionary by the simple process of setting the search 
Start pointers to the name field of the previous definition. If other words 
have been defined since, all of them will be lost. In either case, however, 
the relevant data remains unaltered. It is merely ignored by the search 
processes. This may be compared with the use of OLD after NEW, in 
some versions of BASIC, to restore a program unintentionally destroyed. 

There are many ways to use FORTH. Ata simple level, you can rely on 
the construction of a pyramid of dictionary definitions, with no fancy tricks 
involved. Growing confidence may lead you to explore more complex 
techniques, and eventually you may begin to see how the dictionary 
entries can be modified to make them do what you want. If your ambitions 
lead you along this path, progress with caution rather than speed, for 
there are traps for the unwary, but an attempt will be made to provide you 
with the information you will require. 

In this section, we have encountered: 


1 TRAVERSE Convert TOS from name field start address to 
name field end address. 


—1TRAVERSE Convert TOS from name field end address to 
name field start address. 


CFA Convert TOS from parameter field address to 
code field address. 

LFA Convert TOS from parameter field address to 
link field address. 

PFA Convert TOS from name address to parameter 
field address. 

NFA Convert TOS from parameter field address to 
name field address. 

LATEST Put contents of CURRENT on the stack. (Identifying 
the name field address of the latest entry in the 
dictionary.) 

SMUDGE Change the state of the location defined by LATEST 


by XORing TOS (LOWER BYTE) with the contents of 
that location. 


TOGGLE Change the contents of the location defined by the 
address in 20S by XORing the contents with TOS 
(lower byte). 

FORGET Change the contents of CURRENT to point to the 


name field of the dictionary entry identified by the link 
field of the word which follows FORGET. 
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PART lil: 
Colon Definitions 


This part explains how new words can be created by use of ‘colon 
definitions’, and introduces words related to the branching and looping 
processes. If the use of FORTH were limited to the execution of words 
input from the keyboard, it would be a very limited language indeed, but 
the whole concept rests on the ability to create new entries in the main 
dictionary, or in a subsidiary dictionary created for a particular purpose. 
Once a new entry has been made, it can be used to help to define further 
entries, until a complete program can be defined in terms of a single 
word. 

In compiling new definitions, there are a number of words which are 
unacceptable for direct execution, and these will be examined in due 
course. First, however, some examples of the use of created definitions 
will help to show the possibilities. 


EXTENDING THE DICTIONARY 


In the section on memory access, we saw that a variable entry could be 
extended by ALLOT to reserve an area which could hold an array. 
Access to a given element of the array required a short routine which 
would work out the address of the element: 

nname SWAP DUP + + 

Since n, the number of the required element, and name, the name of 

the array, are variable factors, we can usefully define: 
> ACALC SWAP DUP + +; 

We can now obtain the required address by the shorter entry: 

nname ACALC 


This will have the same affect as the sequence previously defined. We 
Can now go a step further and define: 
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-A! ACALC ! ; 
-A@ ACALC @ ; 

Having defined ACALC , we can now use it to define two words which 
will write to and read from the array element address. This further 
compresses the code required. It would have been possible to define A! 
and A@ directly, without defining ACALC first, but we are dealing with 
principles here, rather than with practice, and the route adopted 
demonstrates the point more clearly. 

In a program examined later on, we will require a three-element array 
called PILE which will be set up by: 

O VARIABLE PILE 4 ALLOT 
We can then access element n of the array by: 
n PILE A@ 
or write to it by: 
n PILE A! 

We must be careful not to make n greater than 2, or we will step outside 
the reserved area. The subscript range, it should be noted, is 0 to 2, not 1 
to 3 as in Spectrum BASIC. If we called 3 PILE A! we would overwrite the 
name field of the subsequent dictionary entry. 

Multidimensional arrays are more difficult to handle. The usual rule for 
calculating an element number n from given subscripts and dimensions 
is based on the iterative application of: 

nN, =Nn,_, “dimension, + subscript, 

Initially, n, = 0, son, = subscript, 

Then n, = subscript, “dimension, + subscript, 

This process is repeated for each subscript in turn. 

For a three-element array, the FORTH sequence would be: 
$3 $2 $1 D2* + D3* + 

This would put the element number on the stack. We can therefore 
define: 

“ELEMENT D2* + D3* + ; 

We could now read from the elements defined by subscripts A1, S2, 
93 by calling: 

$3 S2 $1 ELEMENT ARRAY A@ 
where ARRAY is the name given to the ARRAY. 

In these fairly simple examples, you will note that each definition 
begins with a colon, to instruct the system to create a new dictionary 
entry in compiling mode, and ends with a semicolon to instruct a return to 
direct execution mode. The word following the colon is taken as the name 
of the new entry, and the words that follow are set up in the Parameter 
Field in terms of their Code Field addresses. Note that the colon and 
semicolon are not needed when setting up variables and constants. 
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You need have little fear that you will overfill the available space by 
creating too many definitions. You can always use FREE . to check 
how much space is left, and you will find that it shrinks quite slowly. If you 
want to calculate how many bytes a new definition needs, add up: 


e The number of letters in the new word name, plus 1. 
e Two bytes for the Link Field. 

e Two bytes for the Code Field. 
@ 


Two bytes for each word used, including the semicolon but not 
the colon. 


e Four bytes for each numeric value. 
e Four bytes for a branch or loop. (See next section) 


The word ELEMENT , defined above, takes up 32 bytes. 

You should now be in a position to experiment with the construction of 
some simple sets of words. As you create each new definition, make a 
note of the way it changes the stack. ACALC removes n and an address, 
leaving a modified address in exchange. A! removes n, the address, and 
a single number, while A@ removes n and the address and leaves a new 
single number. ELEMENT removes three subscripts and leaves n. 

lf you note these changes, you will find that it is easier to keep track of 
the overall stack changes, since there is no need to go through each 
definition word by word to see what is happening. 

For the moment, you will be hampered by the fact that your definitions 
soon scroll off the screen and are lost, but a remedy for this will be 
demonstrated in Part IV, when the RAM-Disc system is described. This is 
a storage system in which you can save your definitions and bring them 
back whenever a query arises or you want to amend them. 


BRANCHING AND LOOPING 


Exponents of structured programming regard it as meritorious that the 
FORTH language does not offer a function comparable with the BASIC 
word GOTO, which they regard as unsanitary. In fact, it would be very 
difficult to introduce such a word directly, since there would be no way of 
defining the destination. Inside the dictionary, however, most of the 
branching and looping functions are implemented by relative jumps, 
which are at least near relatives to GOTO. 
The jump functions are: 


BRANCH XXXxX , which transfers action to a link address by adding 
XXXX to the interpretive pointer. 


OBRANCH XXXxX, which acts in the same way, but only if TOS is 
zero. Otherwise, it has no effect. 


since XXXX is a 16-bit word, it would theoretically be possible to jump 


37 


to any other point in the dictionary, but the actual jump spans used are 
relatively small. 

BRANCH , in isolation, is of little value, and is usually employed to 
define an alternative action in association with OBRANCH. In order to 
appreciate the action of OBRANCH , we must consider some of the 
special ways in which TOS can be set to determine whether OBRANCH 
acts or not. 

First, there are simple arithmetic calculations. If they make TOS zero 
at the time when OBRANCH is called, it will act. Otherwise, it will do 
nothing. In either case, TOS will be removed. 

Next come the logic operators, which are not very different: 


— Put a non-zero state on TOS if TOS = 20S, 


otherwise a zero state. 

< Put a non-zero state on TOS if 2OS is less than TOS, 
else zero. 

> Put a non-zero state on TOS if 20S exceeds TOS, 
else zero. 

U< As <, but treating the numbers as unsigned. 


Each of these operators removes TOS and 2OS, and is itself lost when 
OBRANCH acts. It is usual to refer to the item put on TOS by the operator 
as a true flag (non-zero) or a false flag (zero). 

Next there are operators which act on a single value, rather than on the 
comparison of TOS and 20S: 


O< Put a non-zero state on TOS if TOS is negative, else 
zero. 
O= Put anon-zero state on TOS if TOS is zero, else zero. 


Both these operators remove the original TOS. 

The operator O= effectively reverses the state of a flag on TOS, and is 
also called NOT . It may be used after other operators to invert their 
sense. 

A number of other functions leave flags. For example, ?TERMINAL 
puts a non-zero state on the stack if the BREAK combination (CAPS 
SHIFT and SPACE or CAPS SHIFT and 1) is called from the keyboard. 
Other examples will arise from time to time. 


CONDITIONED BRANCHING 


A deceptively familiar branching formatis IF ...ELSE...ENDIF, but 
its action may seem less familiar. It ocurs in the form: 
condition IF action? ELSE action2 ENDIF actions. 
lf condition (on TOS) is true, actions 1 and 3 are performed. If condition 
is false, actions 2 and 3 are performed. The condition flag is removed 
from the stack, and it is sometimes convenient to create it by using 
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—DUP , which only duplicates TOS if it is non-zero. The original TOS 
would then be available for use in action1, but would be discarded if 
action2 was performed. 

The implementation in the dictionary should be straightforward. IF is 
replaced by OBRANCH , which performs an onward jump to action2 if 
condition is zero. Otherwise, a BRANCH at the end of action 1 performs 
an onward jump to action 3. 

Compilation of IF ... ELSE ... ENDIF is checked by a reference 
number which is checked by ?PAIRS . IF sets up 2 , and ELSE requires 2 
to be set. ELSE also sets up 2, and ENDIF requires 2 to be set. It is 
therefore permissible to omit ELSE and action 2 if only one conditional 
action is requied. 

lf you feel it is more expressive, you can replace ENDIF by THEN . 
They mean exactly the same. 

The FORTH ‘ DO loop ’ ts similar to the BASIC * FOR loop ’, the 
equivalent forms being: 


FORN =ATOB...NEXT = B+1ADO...LOOP > 
FORN=ATOBSTEPC...NEXT = B+1ADO...C+LOOP 

Note that the limit parameter is B+ 1, not B. While the iteration index is 
less than the limit, LOOP returns action to a point immediately after DO , 
but when the index is equal to the limit the words following LOOP are 
executed. The Return Stack holds the necessary data. 

DO is compiled as (DO) . When (DO) is executed, it transfers TOS to 
TORS (the initial index value A) and 20S to 2ORS (the limit value B+ 1). 

LOOP is compiled as (LOOP) . When (LOOP) is executed, TORS is 
incremented, and the result is compared with 2ORS to see if the limit 
value has been reached. If it has not, the routine jumps back to a point 
immediately after (DO) , the jump span being calculated at the time the 
sequence is compiled, and set in the word following (LOOP) in the 
Parameter Field. 

+LOOP is compiled as (+LOOP) , which acts in much the same way 
as (LOOP) , except that C (stored in the Parameter Field as a ‘literal’, a 
number to be put on TOS) is added to the index instead of unity. 

Within a DO loop, the iteration index is normally on TOS , unless it has 
been covered by >R, in which case the covering item must be removed 
by R> before (LOOP) is reached. The word R will therefore put TORS on 
TOS, without disturbing the count. For some unexplained reason, a 
synonym of R is commonly used: |. The two words execute in precisely 
the same way, even using the same machine code. By using | , the 
current index value can be used in calculations within the loop. 

The value of 2ORS can be copied to TOS by I’, giving the limit value of 
the index. They can be useful where the required value is (limit — index). 

There is sometimes a need to use the iteration count of an outer DO 
loop, where two loops are nested. For this, 30RS is required, and it can 
be copied to TOS by the word J. 
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There is a slight catch about this. Ifa Return Stack value is read within 
the definition of a word called within a DO loop, a return link has been 
added to the Return Stack during execution of the definition, and it is 
necessary to dig a little deeper, using |’ instead of | , J instead of I’. For 
example: 

: CALC2 I. ; 

‘ CALC1 10 0 DO CALC2 LOOP ; 
Now CALC 1 will print out the numbers 0 to 9. 
So will the listing of CALC1 after defining it as: 


: CALC1 10 0 DO! . LOOP ; 


The return link shows where execution should be resumed in the 
calling sequence Parameter Table. 

In BASIC jumping out of a FOR NEXT loop is sometimes permissible, 
sometimes unwise. To get out of a DO loop prematurely, the word 
LEAVE is used. This sets the index to be equal to the limit value, 
terminating the loop at the next LOOP . LEAVE commonly occurs in the 
format: 


condition IF LEAVE ENDIF 


Less familiar to users of older forms of BASIC, but implemented in 
some recent versions, are the remaining loop formats: 


BEGIN action UNTIL 


repeats action until action puts a true state on the stack. A common 
format to allow manual exit from a loop is: 


BEGIN action ?7TERMINAL UNTIL 


Pressing CAPS SHIFT and 1 will cause ?TERMINAL to return a true 
value on TOS, so that the loop drops out. 

lf no conditonal is set up before UNTIL , the loop may continue for ever. 
Note that UNTIL removes TOS, being implemented by OBRANCH , 
which returns action to just after BEGIN if it finds TOS zero. 

You may use END instead of UNTIL if you wish. They mean the same. 
This is another example of FORTH synonyms, different words which 
mean the same thing, and are executed by the same code. 

A more complex loop structure is provided by: 

BEGIN action1 WHILE action2 REPEAT action3 

WHILE removes TOS. If TOS = 0, action1 is followed by actions. 
Otherwise, action1 and action2 alternate. 

The format BEGIN action AGAIN should be used with caution, as there 
is no way out of the loop other than a call of QUIT , ABORT , or EXIT , 
executed conditionally within action. You have been using QUIT from the 
Start, as it is the routine which accepts user inputs. It clears the Return 
Stack, whereas ABORT clears both stacks, and is more drastic. EXIT 
removes TORS , destroying the link which would otherwise be used to 
direct further action. What happens then depends on what emerges as 
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the new TORS. Within a DO loop, it might be the index count, and that 
would cause mayhem. Experiment with EXIT cautiously, though the 
worst that can happen is that you have to re-load the FORTH tape and 
start again... 
Finally, there is the CASE structure, a special addition to fig-FORTH 
that is omitted in some implementations. The format is: 
condition CASE 

A OF action1 ENDOF 

B OF action2 ENDOF 

C OF action3 ENDOF 

etc. 

ENDCASE 


lf A matches the stated condition, action1 is executed. If B matches the 
condition, action2 is executed, and so on. The condition must be in the 
form of a single number (or the equivalent, e.g. an ASCII code). A, B and 
C can be words or sequences of words producing a similar result. An 
example will be found near the end of the program given in the last 
section of this book. 


STRINGS AND THINGS 


So far, we have only talked about numbers, saying little or nothing about 
text. It is time to remedy that deficiency. 

The word .” compiles a dictionary entry containing the text which 
follows. For example: 


- ABC .” Program Number 1 ” ; 


will set up a dictionary entry which will print the text when the word ABC is 
called. Note that there must be a space between .” and the start of the 
text, and that the text is completed by a further ‘quotes’ character. 

The same definition can include numerics and other words, allowing 
such definitions as: 


BCD 10 6 AT .” ProgramNo2 ”, 


This will position the text on the screen at line 10 column 6. 

Note that in the compiled entry .” is replaced by the link to the 
compiled form (.”) and a character count follows. The actual output is 
performed by TYPE , which outputs TOS characters, taken from an area 
of store starting at 2OS. (TOS and 2OS are removed.) The character 
count is set up by WORD which establishes the number of characters 
and enters the number, with the actual text, in the dictionary. There is 
usually no need to worry about these inner functions. 

FORTH does not have, as a basic provision, any facilities for string 
Slicing. If you want anything like that, you must construct it for yourself. 
The procedure would be to locate the string on which you wish to 
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operate, identify the part of the string you require, and extract that part 
either for immediate use or to form a new entry. An illustration will show 
the method best. 

Define a basic string: 


. DATE .” JanFebMarAprMayJunJulAugSepOctNovDec”’ , 


The sequence —FIND DATE will set TOS to 1, indicating that the word 
DATE has been found, 20S will contain the length byte for the word, and 
308 will contain the parameter field address of the entry. All we need is 
the address: 


—-FIND DATE DROP DROP 3 + CONSTANT POINTER 


This will define a constant pointing to the address plus 3, which is the 
Start of the stored text. We have skipped over the two bytes defining .” 
and the length byte. Note that this sequence is for immediate execution. 
It is not a colon definition. 

To pick out the nth month, we must calculate 3*(n—1) and add it to the 
constant POINTER. That will give us the address of the first character of 
the month name. The address is set in the variable OUT : 


: DATEADD 1 - 3 * POINTER + OUT ! ; 


To get the address of the nth month, we need n DATEADD , so we 
can construct: 


: OUTDATE DATEADD 3 0 DO OUT @ @ EMIT LOOP ; 


The contents of OUT are incremented by EMIT , which outputs the 
character put on TOS by OUT @ @ . The whole month name can now 
be output byn OUTDATE . 

The procedure described above may seem rather complicated at first, 
but it has the advantage of extreme flexibility. 

FORTH also provides facilities for printing formatted numerics. The 
words involved are: 


<# Set up HLD to the address of the text output buffer, as 
held in PAD. This buffer has no fixed address. It floats 
68 bytes above the top of the dictionary. 


# Operates on a double number on TOS/20S, 
generating the least significant digit of its 
representation in the current number base, and 
leaving the residue on TOS/2OS as a double 
number. The digit is stored in PAD, using HLD as a 
decrementing pointer. 

#58 Repeat # until the double number is reduced to zero. 

SIGN Used between <# and #> , inserts a minus sign 
before a converted numeric string if 30S is negative. 
30S is discarded, but TOS/20S are undisturbed. 
They will normally contain the double number being 
operated on. 
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#> Complete formation of a numeric string by dropping 
the double number and leaving the address of its 
location and a length byte. TYPE normally follows. 


TYPE Outputs TOS characters taken from store, starting at 
20S. 


These words allow a rigid format to be set up. Whereas #5 will 
terminate output when the double number reaches zero, a pattern can be 
set up using # which will insert trailing zeroes. There is one more 
provision: 

HOLD Decrement HLD and store TOS in the numeric string 
as an ASCII character code. For example, 46 HOLD 
will insert a decimal point. 


The full capabilities of these words can best be found by experiment. 
Note that a decrementing pointer is used to set up the string in the buffer, 
whereas TYPE uses an incrementing pointer. The least significant digit is 
generated first, but is output last. 

The process can use a DO loop to call # DPL times before the decimal 
point is inserted, DPL holding the decimal point position. SIGN comes 
last, so that its result is displayed or printed first. 

It is convenient to mention here some of the other words that relate to 
strings and text output. 

COUNT, used with TOS pointing to the length byte of a text entry, puts 
the actual length byte on TOS and the address of the start of the 
subsequent text on 20S. TYPE can then be used to output the text. 

. CPU outputs the name of the computer, in case you have forgotten 
which machine you are using . . . 

— TRAILING modifies the length byte of anumeric text string to remove 
trailing spaces. It requires the original length byte on TOS and the 
address of the start of the text on 2OS. It leaves the same situation, with 
the length byte adjusted. It can therefore be interposed between COUNT 
and TYPE, or may precede TYPE when it is used to output a formatted 
string. 

. ID takes TOS as a name field address and ouputs the name of the 
relevant definition. 

The pure string functions in FORTH are not too extensive, as it is 
mainly seen as a calculating language, but quite a lot can be done with 
the facilities provided, given a little thought. 


INPUT/OUTPUT 


The input of keyboard data for immediate execution or for setting up 
colon definitions is so simple that it tends to be taken for granted, but 
quite a lot is done immediately to achieve that simplicity. 

The QUIT routine is used for such input, because it is entered 
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whenever other actions are complete and control is to be returned to the 
user. It invokes QUERY, which puts the address of the Terminal input 
Buffer on the stack, and then the number 80H, which is the size of the 
buffer in bytes. EXPECT is then called to transfer characters from the 
keyboard to the Terminal Input Buffer until either Return is pressed or 
eighty characters have been input. QUERY then zeroes the input pointer 
IN , so that the data which has been input can be scanned. 

This data is in ASCII code form, and needs to be interpreted. Any 
group of codes beginning and ending in a space may be a FORTH word, 
and the dictionary is searched to check this. If no match is found, the 
group may be numeric, and NUMBER is called to check this. NUMBER 
requires a pointer address on TOS, and it checks for a valid numeric in 
terms of the current value of BASE, also looking for a decimal point. If the 
latter is found, DPL is set to the number of digits which follow, otherwise it 
is set to — 1. If the number is not valid, an error is reported. 

lf DPL is positive, INTERRUPT sets up a double number on the stack, 
otherwise setting a single number. If the code group is not identified as 
either a word or a number, INTERPRET reports error. 

An interesting point is that the potential word is entered in the 
dictionary whether it is valid or not, but the dictionary pointer is not 
advanced until the word has been checked, so the word meanwhile has 
no real existence, and may later be over-written. 

If the word is recognised in direct mode, it is executed, while numbers 
are put on the stack, so a continuity of action is maintained, even if the 
input text is supplied in small sections. In compiling mode, compilation 
proceeds in a similar manner. 

While compiled definitions are running, a rather different situation 
applies. The keyboard is ignored unless an input is specifically invited. 
This can be done by: 

KEY Put the ASCII code for a key depressed on TOS. 
INKEY As KEY, but if no key pressed put FFH on TOS. 

The difference is that KEY waits for a key depression, whereas INKEY 
does not. 

These words are convenient for simple control, for responding Y or N, 
or for halting action until you are ready to go on. It is possible to translate 
the ASCII code to a numeric value by using DIGIT, which requires BASE 
on TOS and the character on 20S: 


KEY BASE @ DIGIT 


This will put the numeric value on the stack, then a true flag if the code 
is a valid number, or will put a false flag on the stack if the code is invalid. 
However, the number will not be displayed unless you expand the 
sequence to: 

KEY DUP EMIT BASE @ DIGIT 


It would be possible to extend the sequence further, to accept and 
combine a number of digits as a complete number, but the combination 
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QUERY INTERPRET is more convenient. 

The output of data to the display has been adequately covered 
elsewhere, and the use of 1 LINK to switch the printer on and 0 LINK to 
disable it have also been mentioned. The remaining input/output 
functions are those relating to the ports: 


INP Removes TOS as a port number, and sets TOS as 
the byte read from the port. 
OUTP Removes TOS as a port number and 20S as data. 


The data is output to the specified port. 


A certain amount of care is needed in selecting ports, as some have 
dedicated uses in the Spectrum system. Bits 0 to 4 of the port address 
should be high, and bit 7 should be low, which leaves just four usable 
addresses: 1FH, 3FH, 5FH and 7FH. The limitation applies more 
particularly to output ports. 


ODDMENTS 


A number of quite important words have yet to be mentioned. Those 
associated with the compiling process will be dealt with later, in PART IV, 
but an attempt will be made here to collect together the other straggiers. 

First, there is the word FORTH itself. It calls up the FORTH vocabulary, 
as distinct from any other set of words which may have been defined, 
such as the EDITOR vocabulary. Calling the name of a vocabulary 
switches links within the dictionary so that the required set of words 
becomes available. To be precise, CONTEXT is reset, this being the 
pointer to the start point for searches. An attempt to FORGET a word 
which is not in the currently-selected vocabulary gives error 24, because 
you might destroy a lot more words than you intend to. In any case, you 
will not be allowed to FORGET any word which lies beyond the point 
defined by FENCE, which acts as a protective barrier. 

When you do FORGET a word, you discard not only that word, but also 
every word that comes before it in the dictionary, that is every word that is 
of more recent origin. This is sometimes used to advantage by compiling 
the dummy word TASK as the first word in a program. FORGET TASK 
will then discard the complete program, including any invalid words it 
contains. Such words cannot be forgotten directly. 

The variable STATE determines current working mode, direct 
execution or compiling, and will generate an error if a word inappropriate 
to that state is used. The error checking system employs a number of 
words, a good starting point being 7ERROR, which occurs in the form 
f n ?ERROR, where n defines the error number and f is a flag which is 
true if the error is present. If the flag is false, f and n are cleared from the 
stack and action continues. 


45 


If the flag is true, ERROR is called with non TOS. What happens then 
depends on the contents of WARNING. If WARNING is negative, 
(ABORT) is called, ABORT being called in turn. Otherwise, the offending 
word is displayed, followed by a query, and then MESSAGE is called, still 
with TOS = n, after which the stack pointer is re-initialised and QUIT 
follows. 

WARNING also controls the action of MESSAGE. If WARNING = 0, 
the format ‘MSG # rn’ is displayed. If WARNING is greater than zero, the 
system will display an explicit text message, the text being held in the 
RAM-disc storage system described in Part IV. Since such text would 
pre-empt one fifth of the available storage space, it is not normally used 
in Abersoft FORTH, and it would be completely impractical for other 
implementations which provide less storage space. 

?STACK checks the value of the main stack pointer, reading its 
contents by SP@ and comparing the result with SO, the initialised value, 
and with HERE + 80H. If the pointer is below HERE + 80H, there is a 
risk of conflict with the stored program, and 7ERROR is called withn = 7 
and a true flag. If the pointer is above SO , the stack has been over- 
emptied, and 7ERROR ts called with n = 1 and atrue flag. If neither state 
exists, a false flag is set, and though n = 7 ERROR is ineffective. The 
approach of an error 7 condition can be anticipated by using FREE . to 
display the amount of free space. 

Other error checks are: 


?COMP calls error 17 if the system is not in compiling mode. 
?EXEC calls error 18 if the system is not in direct execution mode. 


?PAIRS calls error 19 if the branching and looping words are not 
correctly paired in sequence. 


?CSP calls error 20 if the stack pointer fails to match the contents of 
the variable CSP, indicating an incomplete dictionary entry. 


?LOADING calls error 22 if the terminal input buffer is in use. 


Subsidiary functions and variables associated with the error system 
are: 


ICSP sets CSP to current stack pointer contents. 

RO The initialising source for the return stack pointer. 
RP@ Reads the return stack pointer to TOS. 

RP! Sets the return stack pointer from RO. 

SP! Sets the calculation stack pointer from 20. 


Finally, in this group, WHERE can be called after an error during 
compiling, whereupon it will pinpoint the source of the error by putting the 
relevant line on display with an accusing arrow pointing to the offending 
word. The verdict is not always accurate. If, for example, a colon is 
missing from the front of a colon definition, the error may only become 
apparent when the semicolon is reached. Provided this is borne in mind, 
WHERE provides a useful aid for debugging source code. 


AG 


Few of the words just described would normally be called by the user. 
Like many others, they are provided for use inside the FORTH system. 

COLD and WARM are a different matter. They allow the system to be 
re-initialised with and without the loss of dictionary extensions. They can 
be called as words, but they are also accessible from BASIC, by GOTO 2 
for COLD and GOTO 3 for WARM. The BASIC system can be entered by 
MON. 

It is sometimes useful to know how big the dictionary is, since it can be 
saved on tape in extended form, and SIZE serves this purpose, by 
putting the number of bytes between ORIGIN and HERE on TOS. 
ORIGIN is a nominal start point for the program, and n+ ORIGIN puts on 
TOS the address of the nth byte from that start point. 

EXECUTE and COMPILE induce entry to the working mode named, 
by setting STATE to the appropriate value. 

NOOP does nothing, except perhaps fill a gap. 

That leaves only the fact that 0 , 1, 2 ,3 are FORTH words in the form 
of constants, saving any need to work out their value, and n USER 
provides the address of a location within the User Variable area, which is 
defined in Appendix A. 

The Appendix will also answer most questions about any word which 
has not been covered as yet, including the EDITOR vocabulary, which 
contains 28 words. However, the examples which will be found in Part V 
should clear up a number of possible obscurities. 


47 


PART IV: 
The RAM Disc 


This part discusses the provisions for storing source code, for saving and 
loading tape copies, and describes the EDITOR vocabulary. 


SCREENS 


One further major facility is needed to make FORTH fully viable. The 
input of colon definitions for immediate compilation can be very tedious, 
especially if frequent alterations are needed. The answer lies in the 
Screens, which store source code for compilation in a way that allows 
changes to be made quickly and fairly easily. 

Spectrum FORTH provides eleven screens, each containing sixteen 
lines of 64 characters. This is the standard FORTH screen format, and it 
is not entirely compatible with the smaller Spectrum display. It leads to 
the user having to put up with some scrolling and using CAPS and 1 to 
BREAK, but this is easily manageable. 

The input n LIST will display and select screen n, but the inital display 
will show lines full of queries, because the store area is full of zero bytes. 
INIT-DISC will fill all the screen areas with space codes. Source code can 
then be entered, using the EDITOR vocabulary, and can thereafter be 
compiled by n LOAD, where n is the number of the screen concerned. If 
--~> is entered at the end of the screen, compilation will continue to the 
next screen. In that way, all ten screens 1 — 10 can be compiled if 
required. 

SAVET will save the entire contents of the RAM disc on tape, and it can 
be reloaded by LOADT or checked by VERIFY, all these words being 
Variations of (TAPE), the common tape system command. All the tape 
files have the name DISC, so you must make your own arrangements for 
identifying one from another. 

What may not be immediately obvious is that a number of sets of 
Screens can be loaded in turn, each being compiled while it is present, so 
that relatively large programs can be set up. 
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FORTH conventions, some enforced by the characteristics of the 
language, impose some limitations on the way the screens are used. 

Screen 0 is reserved for comments and explanation, and cannot be 
used for loading. Similarly, line 0 of each screen is used for a heading, 
and x y INDEX will output the headings of screens x to y. As with all 
comments, the headings should be enclosed between round brackets, 
with a space after the open bracket, as it is a FORTH word meaning 
‘ignore all that follows until a close bracket is found’. The brackets can be 
used as temporary entries to force the system to start compiling in 
mid-screen, the open bracket being set at the start of line 0 and the close 
bracket immediately before the point where compiling is to start. The 
word ,S will cause compiling to stop, as will a null entry anywhere on the 
screen. 

Other conventions arise from the fact that the screens were originally 
intended to work as part of a disk system. This meant that the total screen 
area was effectively as large as a disk, and it was reasonable to allocate 
two screens to the task of supplying textual error messages. Errors 1 to 
15 were supplied by screen 4, and the remainder by screen 5. This facility 
still exists, and can be brought into action by making WARNING equal! to 
1(1WARNING ! ). You will have to enter the messages in the screens 
concerned, but this may be a useful facility while you are getting used to 
the error numbers. You will lose two screens, but that may not be too 
catastrophic in the early stages. 

For printed record purposes, TRIAD is useful. It will display or print the 
content of three successive screens, starting at 0, 3, 6 or 9. Thus 5 
TRIAD would print the group including screen 5, i.e. screens 3, 4 and 5. 

There are a number of words which are provided for use in screen 
handling, but before examining these it will be best to look at the EDITOR 
vocabulary, which is essential for setting up screen data. 


THE EDITOR 


Immediately after loading the FORTH tape, VLIST will display a string of 
words beginning with UDG, the last entry in the basic FORTH 
vocabulary. If you define any new words in that vocabulary, they will 
appear before UDG , being more recent creations. Input EDITOR , and 
VLIST will now show an additional group of words at the start of the 
display. These are the words in the special EDITOR vocabulary. The 
word EDITOR has switched links in the dictionary to bring them into 
action. The word FORTH will switch links again so that the EDITOR 
words are no longer accessible. 

There are almost too many words in the EDITOR vocabulary, and it is 
best to get used to them by degrees. First, you will need to select a 
‘screen and bring it into action in a cleared state. If you want to select it 
without clearance, you need n LIST. At any time thereafter, as long as the 
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EDITOR is enabled, L will also display the screen for line 0. 

The simplest method for entering data into an empty screen is the 
format m P text . This puts the text in line m of the current screen. 

If you could guarantee 100% accuracy in typing and total infallibility in 
the framing of colon definitions, this one command would suffice for 
setting up source code, but there will inevitably be changes to be made. 
The first step is to pinpoint the position at which the change is needed, 
and for that there are useful search facilities, hinging round the cursor 
position, which is stored in the variable R#. 

TOP zeroes the variable, and should be used before a search unless 
you are sure the cursor is above or to the left of the change point. 
Suppose you want to change FIRTH into FORTH . If the offending word 
occurs only once in the screen, TOP X FIRTH will erase it, leaving the 
cursor at the position the word occupied. C FORTH will then insert the 
word FORTH in the same place. Remember that C and X , being FORTH 
words, require a following space before the start of associated text. If you 
input C without text, you will enter a null code, and that must be removed, 
since it acts as a terminator. Fortunately, TOP X will not only locate the 
null, it will replace it with a space. 

If the word you want to erase occurs more than once, you can find the 
first occurrence, without erasure, by using TOP F text , and then N will 
step forward to the next occurrence. When you have found the right 
position, the cursor will be at the end of the text, but B will move it back to 
the start of the text, so that X or C can be used. 

TILL will delete all text from the cursor position to the end of the cursor 
line. 

The cursor can be positioned precisely by nM, which moves the 
cursor n places and displays the resulting position. The value of ncan be 
positive or negative. 

In all these moves and changes, the operative text is held in a buffer 
called PAD, and this can be used to hold lines temporarily in order to 
shuffle the order of lines on the screen. To move line n of the current 
screen to PAD you need n H , while n D will move the text and delete the 
source. On the other hand, n E will delete the line without saving it. 

Once a line is in PAD , and you want to insert it betwen two existing 
lines which are adjacent, n S will move line n and all the lines below it 
down one line, line 15 being lost, and n R will transfer the text from PAD 
into the gap. More simply, n | will perform both operations. 

In cases where the screen is very full, it is sometimes useful to employ 
n T , which types a single line and holds it in PAD. The line can then be 
checked in isolation. 

The remaining EDITOR words are mostly sub-functions of those which 
have been described, and are not normally needed for direct use, but an 
exception is COPY . 

The form a b COPY will copy the contents of screen a to screen b. An 
extension of this uses a negative screen number, which will copy a 
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screen to or from the free space between the dictionary and the stack. If 
free space is limited, it is as well to do a trial run to make sure the area 
used is not occupied, making a dummy transfer from it. 

This facility has the advantage that a screen can be moved from one 
tape record to another. The record originally containing the screen is 
loaded, and the screen is transferred to free space and erased from the 
source screen. The result is saved and verified. The second record is 
then loaded, and the screen is transferred back to a free screen. Being 
outside the normal screen area, it will not have been affected by the 
saving and loading. It can now be saved as part of the second record. 

This little trick can be very useful, but is best performed when there are 
no dictionary extensions and the free space is at its largest extent. 

Perhaps n DELETE should be mentioned. It deletes n characters to 
the left of the cursor position, and is really provided to serve X . The 
remaining words are MATCH , #LOCATE , #LEAD , #LAG , —MOVE, 
— TEXT , 1LINE and FIND . All these are primarily internal words, rather 
than user words. 

lf the editing system has a fault, it lies in the large number of words 
provided. With a little practice, you will find that a small subset will serve 
most purposes. 

It will be noted that two words in the EDITOR vocabulary, R and! , are 
identical with words in the FORTH vocabulary. For direct execution, 
however, the EDITOR forms are found first when the EDITOR 
vocabulary is enabled, so these are used. 

The user words in the EDITOR vocabulary may be summarised: 


B Move the cursor back by the length of the text held in 
PAD. 

C Insert the following text at the cursor position, 
spreading the original text to make room. 

D Remove TOS as a line number of the current screen 


and delete that line after copying it to PAD. 


DELETE Remove TOS as a number of characters, and delete 
that number of characters to the left of the cursor. 


E Remove TOS as a line number and erase that line 
with space codes. 

F Search for match with following text from cursor to 
end of screen. 

FIND As F , but using text already in PAD, and end with 
TOP . 

H Remove TOS as line number, and copy that line to 
PAD. 

| Perform S and R,, inserting line from PAD at line 
TOS . 

L List the currently-selected screen. 
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M Add TOS to cursor position and display line. 

N Find next occurrence of match to text in PAD. 

P Put the following text in the line defined by TOS. 

R Replace line identified by TOS with text in PAD. 

S Move line identified by TOS and following lines down 
one line. 

T Display line and copy to PAD. 

TILL Delete from cursor to end of line. 

X Delete next occurrence of following text. 

TOP Set cursor to zero. 


CLEAR Clear screen identified by TOS. 


BEHIND THE SCREENS 


To preserve at least nominal compatibility with standard fig-FORTH, 
spectrum FORTH includes in its vocabulary a number of words which 
relate to true disk operation, but are not directly relevant to the RAM disc 
system. 

A buffer area is established between CBEO and CFFF, and this 
contains eight buffer areas of nominally 128 byte capacity, four extra 
bytes being provided for control purposes. In a true disk system, these 
would be in direct communication with disk, holding records read in and 
providing data to be read out. 

In general, words which relate to these buffers can be ignored, except 
perhaps for the purpose of adventurous experiment. The words, all 
defined in detail in Appendix A, are: 


Constants: 

#BUFF Number of buffers allocated (8) 

B/BUF Number of bytes per buffer (128) 

B/SCR Number of blocks per screen (8) 

C/L Number of characters per line (64) 

FIRST Address of lowest buffer start (CBEO) 

Hi Address of end of screens area (FBFF) 
LIMIT Address of end of buffer area plus 1 (DOOO) 
LO Address of start of screens are (D000) 
Variables: 

BLK Block number being interpreted. If BLK = 0, the 


TIB is in use aS a Source. 
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OFFSET 


PREV 


USE 


SCR 


Functions: 


+BUF 


-LINE 


BLOCK 


BUFFER 


DRO 


Can be used to displace the screens area, this 
being equivalent to moving to a different disc 
area. Best left at zero. 


Holds the address of the most recently used 
buffer. 


Holds the address of the least recently used 
buffer. 


Holds the number of the screen in use. 


Removes TOS as the address of the current 
buffer, and selects the next buffer in sequence, 
putting the address of the latter on 20S anda 
flag on TOS. If the new buffer is that identified 
by PREV, the flag is false. 


Removes TOS as a screen number. If that 
block is held in a buffer, the address of the 
buffer is returned on TOS. Otherwise the 
contents of the buffer identified by USE are 
read to disc (in this case RAM disc) and the 
block is copied into that buffer, the address of 
which is returned to TOS. 


Removes TOS as a block number. if that block 
is held in a buffer, the address of the buffer is 
returned on TOS. Otherwise the contents of the 
buffer identified by USE are read to disc (in this 
case RAM disc) and the block is copied into that 
buffer, the address of which is returned on TOS. 


Removes TOS as a block number, and assigns 
the next buffer to that block, first saving the 
buffer contents on disk if they have been 
updated. The address of the buffer is put on 
TOS. (BLOCK uses BUFFER) 


Set OFFSET = 0 


EMPTY-BUFFERS Set up the control fields of all buffers to the initial 


FLUSH 
LINE 


state, i.e. as empty. 
Write all updated buffers to disk. 


Removes TOS as a line number, and returns 
the address of the start of the line in the current 
screen. 
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R/W 


TEXT 


UPDATE 


Removed TOS as a flag, 20S as a block 
number, and 3OS as an address. If the flag is 
false, data is written from the buffer to disk 
(RAM disc). If the flag is true, a read operation is 
performed. 

TOS is removed as a delimiter, and the 
following text is copied to PAD. 

The buffer identified by PREV is marked as 
updated, i.e. its contents have been altered. 
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PART V: 
Simple Programs 


In this part, some simple programs will be discussed as examples. 


SIMPLE PROGRAMS 


Armed now with all the facts needed, we can begin to look at some simple 
programs. As a start, how about a program to dump store data and 
display it? 
SCR #1 
(DUMP PROGRAM) 
: TASK ; 
: PLINE CR DUP 5 U.R 8 0 DO 
DUP C@ 3 .R 1+ 
LOOP ; 
: PBLOCK CR 16 0 DO PLINE LOOP ; 
: GETN QUERY INTERPRET ; 
: DUMP HEX CLS .” Start Address ?” 
GETN BEGIN PBLOCK CR KEY DROP 
?TERMINAL UNTIL ; 


OCOOnN Oot AN = CO 


Set the program up in screen number 1, check and if necessary correct 
any errors. Then call FORTH 1 LOAD, and thereafter the word DUMP will 
call the program. In most BASICs, it would be much longer, to obtain the 
required format and to perform the hexadecimal conversions. 

This is not laid out in formal FORTH style, but it will still load perfectly 
well. Note the use of TASK at the start, so that the program can be 
forgotten by FORGET TASK. 


7 


PLINE performs a newline, then duplicates TOS, which holds the 
current dump address. The copy is used to display the address in a 
five-position field (5 U.R) and then an eight-iteration loop is entered 
which again duplicates the address, reads the contents of the location 
defined, and displays the result in a three-position field. The address, on 
TOS again, is incremented, and the loop iterates. The overall result is a 
single line dump. It is in hexadecimal, because DUMP sets that 
condition. 

PBLOCK repeats PLINE sixteen times, putting in an extra newline first. 

GETN puts the required start address on TOS. 

DUMP , the overall word for the program, sets HEX working, clears the 
screen, and puts up the invitation to input a start address. That might 
equally well have been included in GETN , to show the purpose of that 
word more clearly. The BEGIN-UNTIL loop then repeats until BREAK 
(CAPS SHIFT and 1) is pressed, but the action pauses after each block 
until a key is pressed. Note that the result of KEY is dropped, being 
unwanted. 

Set the program up in screen number 1, check it and if necessary 
correct any errors. Then call 1 LOAD, and thereafter the word DUMP will 
call the program. In most BASICs, it would be much longer, to obtain the 
required format and to perform the hexadecimal conversions. 

You may want to see text, rather than hex codes. Very well, we need to 
change PLINE as follows: 


; TPLINE CR DUP 5 U.R SPACE 16 0 DO 


DUP C@ 32 MAX DUP 160 > IF 128 — ENDIF 
EMIT 1+ LOOP : 


As there is only one character per location dumped, we can put sixteen 
locations in a line. We don't want codes below 32 to be displayed, which 
would create mayhem, so we put 32 MAX, so that 32 is taken if the 
previous TOS was less. Codes above 160 are in the token area, so for 
these we subtract 128. We use EMIT, to output the ASCII code 
character instead of the hexadecimal value. 

These two simple routines raise a number of important points. As we 
have changed the name of the definition from PLINE to TPLINE , it will 
not be called by PBLOCK , and we have to make a new version of 
PBLOCK called TPBLOCK and a new version of DUMP called TDUMP . 
GETN need not be duplicated if it had already been loaded. 

lf we had called the definition PLINE it would have made no difference, 
because PBLOCK would still refer to the original PLINE , the one which 
was defined before PBLOCK . 

Using the editor, it is fairly simple to copy page 1 to page 2 and alter 
names as necessary, with the TPLINE definition at the top. 

The next point concerns numbers. The loading was done with the 
system in the DECIMAL state, so the numbers are given in decimal form. 
HEX is not executed at line 7 of screen 1 , because it is being compiled. It 
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is worth noting that LIST sets the DECIMAL mode for its own purposes, 
So it is usually best to use decimal values in source code. If hex values 
are more convenient, you only need to insert HEX , outside a definition 
so that it will be executed, not compiled. 

What next? Well, a notable absence from the dictionary is any kind of 
random generator, and most programs need one sooner or later. Here is 
one possibility: 

O VARIABLE SEED 
‘ MODSEED SEED @ 75 U* 75 0 D+ 
OVER OVER U< ——1 -— DUP SEED ! ; 
> RND MODSEED U* SWAP DROP ; 
: RAND —DUP O= IF 23672 @ THEN SEED! ; 

RAND is a randomizer. 0 RAND will set SEED from the low byte of 
FRAMES . If TOS is non-zero, its value will be set in SEED. 

RND is the actual random generator from the user point of view. It is 
used in the form n RND , which generates a number between 0 andn. 
MODSEED changes the value of SEED and creates the basic random 
number between 0 and 1 by which n is multiplied. 

The actual working of the words is less important than the result they 
give. Here are some definitions that allow you to check the randomness: 

O VARIABLE ARRAY 62 ol 
‘ AGEN ARRAY SWAP 2 * 
: A! AGEN ! ; 
: A@ AGEN @ ; 
: ZERO 32 0 DO 0! A! LOOP :; 
‘ SETUP O RAND 1000 0 DO 32 RND DUP A@ 1+ 
SWAP A! LOOP ; 
: DISP CR 32 0 DO | A@ 8 .R LOOP ; 


: GRAPH CLS 32 0 DO! 8 * O PLOT 18 * ! A@ 
DRAW LOOP ; 


> CHECK ZERO SETUP GRAPH ; 
: DISCHECK ZERO SETUP DISP ; 


An array of 64 bytes is set up. ZERO clears the array to zero. SETUP 
then generates a thousand random numbers in the range 0 to 32 (never 
actually reaching 32) and adds one to the nth array element every time 
the number n results. Two options are available for checking the 
randomness. DISCHECK calls ZERO SETUP DISPLAY , which displays 
the 32 numbers in the array in four columns. CHECK SHOWS THE 
RESULT AS A HISTOGRAM. A more stringent check can be made by 
increasing the size of the DO loop in SETUP. 

These simple programs are worth analysing in some detail. You may 
find that you can improve on them. There are often alternative ways of 
doing the same thing in FORTH. You may find that the stack 
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manipulations are worth following through. Try combining the GRAPH 
and DISP routines to give you a graph with numbers. 

Above all, experiment with some routines of your own. If you feel short 
of ideas, pick out a fairly simple BASIC program and set about converting 
it to FORTH. lf the original is untidy, you will need to sort it out first, 
because FORTH programs have to be structured. That means they have 
to be laid out in a coherent way. In particular, the definitions must be in 
the right order. 

In the next section, we will examine the approach to writing a 
somewhat larger program than those already given. 


PLANNING A PROGRAM 


The classic ‘Towers of Hanoi’ problem will be used as a basis for 
illustrating the way a program is planned. The problem involves a 
number of discs of different sizes arranged in three piles. Starting with all 
the discs on pile 0, they must be moved, one disc at a time, to pile 2, no 
disc ever being placed on top of one smaller than itself. 

The overall structure of the program will be roughly: 


Display the title 

Set up initial conditions 

Move the discs 

Ask if a repeat is wanted 

If so, repeat from initialisation. 


The first step is to decide the display format. It will be convenient to put 
the pile centres in the 6th, 17th and 28th columns. For graphic plotting, 
the horizontal coordinates will be approximately 43, 131, and 219. 
Approximately, because to get them in the centre of the pile numbers it 
would be necessary to create special characters for the numbers, since 
the normal numbers have no centre dot position. 

if we make the nth disc 6*n dots wide, we will be able to handle up to 
twelve discs. 

The working method must then be decided. The flow chart given here 
shows an approach which uses nejther recursion nor empirical fiddles, 
and is defensible on the grounds of simple logic. Each move is specified 
by three stack items. TOS gives a disc number, and will be shown as n; 
20S holds the number of the pile from which the disc is to be taken, and 
will be shown as s; 30S holds the number of the pile to which the disc is to 
be moved, and will be shown as d. 

lf n discs are to be moved, the initial top-of-stack items must be 20n, 
asking for a move of disc n from source 0 to destination 2. That move can 
only be made if all the other discs are on pile 1, and the GEN1 function 
calculates 2 1 n-1 as a prior move. That, however, requires 20n-—2asa 
prior move, and so on. GEN1 takes the original three top stack items ds 
and n and creates three more which are related to them as follows: 
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TRANSFER 


Y DROP THREE 
ITEMS 
MODIFY LAST 
MODE (GEN2) 


FLOW CHART FOR TOWERS OF HANOI! MOVE FUNCTION 
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The new 30S is the same as d, the original 30S. 


The new 20S is calculated as 3 — d — s. Since the total of all the 
pile numbers is 3, this will identify the pile not involved in the original 
move. 


The new TOS is one less than the original TOS. 


When repetition of this process reduces TOS to 1, the actual moving 
process can begin. If there are five discs, the stack contains: 
205104203102201 
The 2 0 1 and 1 0 2 moves can be made, putting disc 1 on pile 2 and 
disc 2 on pile 1 . Before the third move, 203, can be made, an extra move 
is needed to clear pile 2. It is calculated by GEN2, which modifies an 
existing move, rather than adding a new one. The change is: 


The new 30S is calculated by 3 — d — s. 
The 20S is unaltered 
TOS is decremented. 


This, in the above context, gives 12 1 , moving disc 1 from pile 2 to pile 
1. 

lf a move sequence is worked through on this basis, it will be found that 
the moves generated are those required to make the specified move. 
Note, however, that n can have two meanings. It may mean disc n, or it 
may mean n discs. The distinction is unimportant in practice. 

GEN1 will obviously be a FORTH word. It will first have to copy 30S, 
and a special sub-word will help in that respect: 


; SOVER >R OVER R> SWAP ; 


TOS is passed to TORS while OVER copies 30S as a new TOS. After 
the original TOS is restored, SWAP brings the copy of 30S to 20S. The 
original stack ds n becomes d snd. 

GEN1 can then be defined: 


: GEN1 S3OVER 3 SWAP — 30VER — 30OVER 3OVER 1 — ; 


Like all new words of any complexity, this should be checked by 
tabulating the stack changes: 


Stack 
dsn 
30OVER dsnd 
3SWAP— dsn3-d 
3O0VER— dsn3-d-s 
3OVER dsn3-d-ss 
30VER dsn3-—d-ssn 
1— dsn3-d-ssn-1 
The three new items have been added without affecting the rest of the 
Stack. 
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GEN2 may similarly be defined: 


: GEN2 ROT DUP >R 3 SWAP — ROT — 
R> SWAP ROT 1 — ; 


Checking stack changes: 
Stack 
dsn 
ROT snd 
DUP >R snd TORS =d 
3 SWAP— sn3-d 
ROT n3-ds 
— n3-—d-s 
R> n3-—d-sd 
SWAP nd3-d-s 
ROT d3-d-—sn 
1— d3-—d-sn-1 


We now need to consider the TRANSFER function. It must erase disc 
nin its present position, and display it in its new position. In the process, 
the stack must not be altered, since GEN2 may need the data. If GEN2 is 
not involved, the three move-defining items will be dropped. It would no 
doubt be possible to achieve this by use of the stack alone, but it will be 
simpler to make use of some variables and an array. The variables are 
DSIZE (half width of the disc in dots), XPOS (vertical centre line of disc as 
a dot coordinate), and YPOS (vertical coordinate of bottom of disc). 

The array is PILE , and it holds the number of discs on each pile. As 
there is only one array, we will set it up as follows: 

O VARIABLE ARRAY PILE 4 ALLOT 
: AGET PILE SWAP 2 * + ; 

- A! AGET ! ; 

: A@ AGET @ ; 

The address of element P will be put on TOS by P AGET, and the 
contents of the element can be accessed by P A@ . We can write to the 
element by X P A! , where X is the data to be written. 

Since the numbers involved are small, we could have used a three 
byte array instead of a three word array, but the point is not too important. 

By invoking the BASIC function OVER, we can use the same routine to 
both draw and erase discs: 


: DDRAW 1 GOVER 6 0 DO (Draw six horizontal lines) 


XPOS @ DSIZE @ — (x inPLOT = XPOS—DSIZE) 
YPOS @ | + PLOT (y in PLOT = YPOS+1H) 
XPOS @ DSIZE @ + (x in DRAW = XPOS+DSIZE) 
YPOS @ | + DRAW (y in DRAW = YPOS+]) 


LOOP 0 GOVER ; 
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We now need a routine to translate the three top of stack items to the 
required variable values: 


: SETUP OVER OVER (Stack d s n tod s ns _n) 
3 * DSIZE ! (DSIZE = 3*n) 
DUP A@ (Stack ds n_s_ PILE(s)) 
1+ 8 * YPOS ! (YPOS = _ 8*(PILE(s) + _ 1)) 
88 * 43 + XPOS ! (XPOS = s*88 + 43) 
DDRAW ; 


This would erase the top disc on pile s. To insert the same disc on pile 
d, e must first adjust the contents of the PILE array to take the move into 
account, and then call SETUP again with the stack temporarily changed 
froomdsntodsdn; 
: ADJUST OVER AGET —1 SWAP +!(Decrement PILE(s)) 
3OVER AGET 1 SWAP +! ; (Increment PILE(d)) 
-: TRANSFER SETUP ADJUST 30VER 
SWAP SETUP SWAP DROP ; 


Finally, to complete the flow chart, we need: 


: CHECK 0 A@ 1 A@ + ; (Returns 0 when move 
complete) 
The word MOVE , covering the flowchart, can now be defined: 
: MOVE BEGIN CHECK WHILE 
BEGIN DUP 1 > WHILE 
GEN1 
REPEAT 
BEGIN 
CHECK IF TRANSFER ENDIF 
DUP 1 > NOT WHILE 
DROP DROP DROP 
REPEAT GEN2 
REPEAT 
Compare this with the flowchart. 
We now require INIT, which will have the form: 


: INIT ENQUIRE (Ask how many discs) 
LINEDRAW (Draw the base line) 
PILEDRAW (Draw the initial pile) 

WAIT (Pause before beginning MOVE) 

: ENQUIRE 2 0 (Initial destination and source) 
CLS 10 5 AT (Clear screen, position text) 

How many discs ?” 
QUERY INTERPRET (Get response) 
2 MAX 12 MIN ; (Limit range) 

: LINEDRAW 1 INK (Blue line) 

CLS 20 0 AT (Clear screen, position line) 


“(5 RVSP) 1 (10 RVSP) 2 (10 RVSP) 3 (4 RVSP)” 
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2 INK ; (Red discs) 
In the above, 10 RVSP means ten reverse video spaces, Graphic 8. 


: PILEDRAW 3 0 DO 01 A! LOOP(Zero array elements) 
OVER OVER DUP 0 DO (Stack ds nto d Ss ns n) 


O AGET 1 SWAP +! (Increment PILE(0)) 
| — SETUP DROP OVER (Drawdisc n—|. Restore n) 
LOOP DROP DROP ; (Discard unwanted items) 


We need a function to respond to a request to run again: 

: ASK 0 0 AT . “ Again ?” KEY 89 — ; 
This will return Zero if key Y is pressed. 
We also need a title function: 

; TITLE CLS 10 6 AT . “THE TOWERS OF HANOI ” WAIT ; 
All that remains is to define the top level function: 

- HANOI! TITLE BEGIN INIT MOVE O INK ASK UNTIL ; 
We can now construct a hierarchy of functions, showing how each 


Stands in relation to the others, and this will serve as a basis for deciding 
the order in which they should be compiled: 


Definitions in the right hand column must be set up first, then column 
by column to the left. The order is not completely rigid, providing the 
necessary priorities are observed. A possible layout on four screens is 
shown in the attached listing. 

This is a moderately complex program, mainly because of the 
commitment of the stack to the move data. it was chosen as illustrating a 
wide range of techniques, without becoming too abstruse. 

It is always wise to save the screens on tape before actually running 
such a program. A slight error in entry can cause lockup or some other 
malfunction, and all stored data may then be lost. 
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HANOI! TITLE ——WAIT 








INIT ENQUIRE 
LINEDRAW 
PILEDRAW SOVER 
WAIT PILE 
———— AGET—— PILE 
AGET-—— PILE 
MOVE CHECK ———————--—— A@—_ AGET -_ PILE 
—GEN1 — 0 VER 
GEN2 
TRANSFER-— SETUP DSIZE 
—_—__— AGET——_- PILE 
XPOS 
YPOS 
XPOS 
YPOS 
DSIZE 
ADJUST 3OVER 
L AGET — PILE 





3OVER 


ASK 
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CR # 1 


: TASE ;: 


MNOnN OW P Whe 8 WH 


: A! AGET ! 
:s AG@ AGET @ 


Q@ VARIABLE DSIZE 

® VARIABLE XFOS 

®@ VARIABLE YFOS 

@ VARIABLE PILE 4 ALLOT 

: SOVER >R OVER R> SWAP ; 
AGET FILE SWAF 


> e + 3 


( THE TOWERS OF HANOI: 1) 


$ 


iQ : DDRAW 1 GOVER 6 @ DO 


i1 XFOS 
12 YFOS 
12 XFOS 
14 YFOS 
1S LOOF 


SOCK # 2 
( THE TOWERS 


SOnNGCOPWU He G 


DSIZE @ - 

I + FLOT 
DSIZE @ + 

I + DRAW 
GOVER 3 --> 


OF HANOI: 2) 


: SETUF OVER OVER 
o * DSIZE ! 
DUF AG 
1+ 8 #* YFOS ! 
S88 # 43 
DDRAW 
s ADJUST OVER AGET -1 SWAF + $! 
-<OVER AGET 1 SWAF + ' 3; 
: WAIT 20800 @ DO LOOF ; 


+ XFOS ! 


1M : ENQUIRE 2 @ CLS 10 35 AT 


How many discs?" 
QUERY INTERPRET 
= MAX 


12 MIN ; 


14 : CHECE @ AG 1 AG + ; 


15 --: 


SCR # 3 


( THE TOWERS 
: LINEDRAW 1 INE 


OF HANOI: =) 


CLS 20 @ AT 


22080 99800 Foret cuuty erete orawe wwete COhpD GOERe aetee Scere ewhte Sbwee coumD GED meen 60080 BOOED wbEte ObE8O COtET EEtee COTTD Ghat anete aheee hast fete 00000 


Q@ DO I A! LOOF 
OVER OVER DUF @ DO 


: FILEDRAW 3 


fPijPe & 
pat 
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IF TRANSFER ENDIF 


Again ?" KEY 89 - 


= @ AGET 1 SWAP +! 

& I ~ SETUF DROF OVER 

7 LOOF DROF DROF ; 

8 : GEN1 SOVER 3 SWAF — SOVER 

9 — SOVER ZOVER i - ; 
i@ : GEN2 ROT DUF =R 3 SWAP — 
il ROT ~ R= SWAF ROT i - : 
i2 : TRANSFER SETUF ADJUST 3O0VER 
1% SWAP SETUF SWAF DROF ; 
14 : INIT ENQUIRE LINEDRAW 

iS FILEDRAW WAIT 3; -—> 
SCR # 4 

@ ( THE TOWERS OF HANOI: 4) 

1: TITLE CLS 10 @ AT 

2." THE TOWERS OF HANOI” WAIT ;: 
3 : MOVE BEGIN CHECK WHILE 

4 BEGIN DUF 1 > WHILE 
a GEN1 

b REFEAT 

7 BEGIN 

Sg CHECK 

9 DUF 1 > NOT WHILE 
i@ DROF DROF DROF 

it REFEAT GEN? 

i> REFEAT ;: 

iS : ASE @@ aT." 

14 : HANOI TITLE BEGIN INIT 


MOVE @ INE ASK UNTIL ; 
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PART VI: 
Compiling 


This part covers the words which are used in compiling, and explains 
some of the less obvious ways in which such words can be used. 


COMPILING 


When the system is in compiling mode, most of the words that it finds in 
the input stream are incorporated in a new dictionary entry. Each word is 
located by searching through the dictionary, and the address of its Code 
Field is added to the new Parameter Field. Some words, however, are 
treated differently. 

Words which have the ‘precedence bit’ in their length byte set true are 
not compiled, they are executed. For example, the definition of the word 
DO is: 

COMPILE (DO) 
HERE 
3 


The first line enters the Code Field address for (DO) in the Parameter 
Field, and HERE then saves the contents of the dictionary pointer for use 
later, the contents being held on the stack. Then 3 is put on the stack, this 
being the check number for a DO — LOOP combination. 

The definition of LOOP is: 

3 ?PAIRS 
COMPILE (LOOP) 
BACK 

Another 3 is put on the stack, and 7PAIRS compares this with 2OS, 
which should contain the 3 left by DO . If it does not, then some error has 
been made, such as a failure to balance another type of loop format. 

If the comparison shows a match, the Code Field address for (LOOP) 
is added to the new Parameter Field, and then BACK is called. This again 
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calls HERE to put the contents of the dictionary pointer on the stack, and 
performs a subtraction. The result is written to the new Parameter Field, 
being the jump span needed to reach a point immediately after the (DO) 
entry. 

Similar procedures apply with other branching and looping 
combinations. 

Colon and semicolon also have the precedence bit set. Colon first 
checks that the system is in direct execution mode, since it is not 
permissible in compiling mode. Then the current stack pointer is saved in 
CSP as a reference, and CONTEXT is set equal to CURRENT to ensure 
that the right value of dictionary pointer is used, putting the new word into 
the selected vocabulary. CREATE then sets up the first two fields of the 
new entry. The Code Field is set to point to a short machine code routine 
which establishes conditions for interpretation of the Parameter Field by 
saving the current Instruction Pointer value on the Return Stack and 
setting the pointer to a new value, the start of the parameter field. The 
Instruction Pointer is used to read the link addresses and other data 
required for execution. 

semicolon reverses the process. It expects to find that the stack 
pointer has returned to the value saved itn CSP by colon, and issues an 
error report if this is not the case. Then ,S is compiled into the last 
position in the Parameter Field, the ‘smudge’ bit is set to the valid state, 
and direct execution is resumed. When executed, ,S removes the return 
link address from the Return Stack and sets it in the Instruction Pointer. 

such processes can be forgotten for most purposes, but they can be 
important if you want to play tricks in setting up new words. Some of the 
definitions given in Appendix A look simple enough, but if you try to 
compile them directly you may find that the system objects. 

Take, for example, the words formed by square brackets. The colon 
process uses ] to switch to compiling mode, and semicolon uses [ to 
return to direct execution. All these words do is to change the contents of 
the STATE variable, but they are still very useful, allowing an interlude of 
direct execution in the middie of a compiling process. This might be used 
to calculate a critical value that depends on a word compiled earlier. 

Colon also uses ;CODE , which compiles (,; CODE) . When executed, 
(;CODE) sets the Code Field of the most recently compiled word to point 
to a machine code routine which follows ;CODE . In the case of colon, the 
actual machine code is called by all definitions that have a real 
Parameter Field. If an assembler were available, it would be entered 
automatically to set up the code in question. in its absence, the words , 
and C, can be used. Comma stores TOS in the next dictionary location, 
while C, stores only the low byte of TOS. By using these two words, it 
would be possible to set up a new definition directly, but that would be 
rather a waste of time and effort. However, it is sometimes useful to use 
the words to set up specific links or data within a Parameter field, or data 
within an array. in the latter case there is no need to use ALLOT to make 
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room for the array, as comma and C, both advance the dictionary pointer 
to the first empty location. 

Perhaps the oddest word in FORTH is the one with a Name Field that 
contains C1 80 . A length of 1 letter, in other words, and that letter is 
conveyed by 80H — 80H = 0. Anull code is used to terminate screens 
and buffers, and it will stop interpretation. If a null is accidentally inserted 
in the middle of a screen, it will be found impossible to interpret the 
screen beyond that point. 

LATEST puts on the stack the Name Field address of the most recently 
defined dictionary entry. This is used by IMMEDIATE , which sets the 
precedence bit for that entry, allowing words to be defined that will 
execute in compiling mode. 

On the other hand, [COMPILE] will cause the following word to 
compile, even if it has a true precedence bit. The possibilities which this 
opens up are slightly mind-boggling at first. It is possible to visualise 
words that will set up DO loops or other looping or branching functions. 
However, the classic example is: 

> XXXX [COMPILE] FORTH ; 

Without [COMPILE], the word FORTH would execute when XXXX was 
compiled, leaving the definition of XXXX as ‘no action’. As it stands, the 
colon definition will be equivalent to FORTH , and executing XXXX will 
select the FORTH vocabulary. In a sense, [COMPILE] defers the action 
of the word on which it acts, making it effective at execution time, rather 
than at compile time. 

Next we have two important words which are rarely seen: LITERAL 
and DLITERAL. They are called when INTERPRET finds a numeral in 
the input stream. In direct mode, they do nothing, since the numeral is put 
on the stack and remains there. In compiling mode, LITERAL compiles 
LIT and then uses comma to transfer the numeral from the stack to the 
Parameter Field. When the field is interpreted, LIT transfers the numeral 
back to the stack. DLITERAL acts in a similar way, but compiles LIT , then 
TOS, LIT again, then 2OS. As the D suggests, it is intended to deal with 
double numbers. 

CREATE sets up the first two fields of a dictionary entry, using WIDTH 
to check that the length of the name is within valid limits. WIDTH is a 
variable, normally set to 31. 

The word ‘tick’ is sometimes useful. In the form: 


"XXXX 


in direct execution it puts the Parameter Field address of XXXX on the 
Stack. In compiling, it transfers the address as a LIT entry in the new 
Parameter Field. 

At this point, it is necessary to call a halt. The words which are more 
likely to be of direct use in the compiling process have been described, 
with one exception, which is complex enough to merit a section of its 
own. 
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A fascination and a frustration of FORTH is that there are many slightly 
esoteric tricks that you can play with it, so many that it would be pointless 
to try to explain them all. The programs given in this book provide some 
illustrations, but by no means cover the full range of possibilities. You 
have to invent your own solutions, since they are probably aimed at 
solving problems that are not common enough to have generated ready- 
made answers. 


<BUILDS...DOES> 


It has been said that the <BUILDS .. .. DOES> combination is both one 
of the most powerful facilities in fig-FORTH and also one of the most 
difficult to explain. It is a tool used to perform complex processes which 
create other tools. Here is an example: 


- ARRAY <BUILDS 2 * ALLOT DOES> SWAP 1 — 
o2* +; 
This creates a new word ARRAY, which can be used as follows: 
8 ARRAY HEAP 


This will create a one-dimensioned array called HEAP with space for 
nine two-byte words, the 8 specified plus one from the basic variable, as 
in the simpler methods of array creation already discussed. All this is 
done by the 2 * ALLOT following <BUILDS , but there is more. If we call 5 
HEAP , the words following DOES> will decrement 5 to 4 , double the 
result, and add the array base address. Thus n HEAP @ will read the nth 
element of the array, n HEAP ? will display that element, and mn HEAP ! 
will set the element to m. 

The word ARRAY remains available as a tool to establish further 
arrays of a similar kind. It will be seen that it saves a lot of trouble in 
relation to the methods described earlier. 

The point to grasp is that the words following <BUILDS are used to 
determine the basic form of the new word, while the words following 
DOES > determine the process which will be associated with it. 

Here is a more complex example which handles two-dimensional 
arrays and checks the subscripts to ensure that they are within the 
bounds defined by the given dimensions. Three new words are involved, 
and compilation is carried out with hexadecimal notation selected for the 
sake of convenience and clarity. 

HEX 
: OFB . “ Outof array bounds. ” SP! QUIT; 
: OFBCK >R ROT ROT DUP R> DUP FF AND ROT < IF 
OFB ENDIF 100 / 
>R OVER R> DUP ROT < IF OFB ENDIF ; 


: ARRAY2 <BUILDS FF AND DUP C, SWAP FF AND 


T2 


DUP C, * 2 * ALLOT DOES> DUP @ OFBCK SWAP 
1—* + +; 

With these words defined, an array is created, with dimensions x and y, 
by: 

x y ARRAY2 MATRIX 

The dimensions are stored at the start of the array, and the number of 
bytes reserved is 2*x"y . This is all determined by the words following 
<BUILDS . The words following DOES> take effect wnen MATRIX is 
executed. Note that x and y are stored by C, and they therefore occupy a 
byte each. DUP @ puts them both on TOS, while preserving the 
subscripts behind them, OFBCK is then called to compare the subscripts 
with x and y , and to report if the subscripts are out of range. Work through 
the stack changes, but remember that hexadecimal notation is used, so 
that a division by 100 is really a division by 256, which will bring the upper 
byte of TOS into the lower byte position. 

These examples illustrate the use of <BUILDS ... DOES> ina 
particular context, but the general concept should be clear enough. 
Broadly speaking, <BUILDS establishes a constant, and the 
subsequent code extends the compilation. DOES> uses a standard 
segment of machine code to perform a little sleight of hand so that the 
words which follow it are appended to the entry created by <BUILDS . 

There are other ways of creating compiling tools, but the best way to 
learn about these is to try various combinations and check on the 
definitions that result. 


READING THE DICTIONARY 


It is sometimes useful to be able to see how the code you have defined 
has been set up in the dictionary. For this, a simple program is: 


: SCAN BEGIN CR 
DUP @ 2+ NEFA ID. 
KEY CASE 
68 OF 2+ DUP @ U. 2+ 0 ENDOF 
69 OF 1 ENDOF 
70 OF 2+ O ENDOF 
ENDCASE UNTIL ; 


: $ -FIND QUERY INTERPRET 
IF DROP CLS SCAN 
ELSE . “ NOT FOUND ” ENDIF ; 

Input $ followed, after a space, by the name of the definition you want 
to examine, and press return twice. The first name will appear at the top 
of the screen. Press F to get the next name, unless the first is BRANCH , 
OBRANCH , LIT , (LOOP) or (+LOOP) . All these have data words 
following, and these and the next word can be obtained by pressing D . 
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To end, press E . The end of the definition is usually marked by ,S . If you 
continue after that, all sorts of strange things may happen. 

lt would be nice, of course, to make the special names call up the 
appropriate action, so that it was all automatic, but there would still be a 
problem with (.”) , which is followed by text. To continue, it would be 
necesary to scan past the text, which would not be too difficult. If you 
want to use this routine a lot, you should be able to work out how to make 
it more automatic. 

In considering jump spans, remember that they represent a number of 
bytes, and each word or data link occupies two bytes. A branch span of 
ten will thus go ahead five entries. 

One small oddity. It is necessary to load the above programs in 
DECIMAL , as the three ASCII codes 68, 69 and 70 are in that form. The 
program, on the other hand, is best run in HEX . How would you ensure 
that these requirements were met? 


MORE COMPILING 


The normal compiling system automatically keeps watch on the progress 
of compilation, and when you try less direct methods you must be 
prepared to do the same. You need to examine the detailed structure of 
the words you use, and that is one of the reasons why APPENDIX A has 
been provided. 

In the section of the Appendix covering the EDITOR vocabulary, you 
will find a slight oddity. The words R and | have been redefined, but 
subsequent definitions use the earlier meanings. To achieve this sort of 
trick, it is only necessary to insert the word FORTH at a suitable point, 
whereupon the FORTH versions of the words will be compiled. The word 
EDITOR will later ensure that the definition is continued on the basis of 
EDITOR words already defined. 

To set up a special vocabulary, you must first establish the word 
SPECIAL (or whatever you want to call it) by the entry: 

VOCABULARY SPECIAL 


This puts an entry in the FORTH vocabulary. To select the SPECIAL 
vocabulary, you need: 


SPECIAL DEFINITIONS 


Words compiled thereafter will be put into the SPECIAL vocabulary. 

Why have a special vocabulary ? One good reason is that too large a 
vocabulary slows down compiling, and access to a specialised 
vocabulary can be much faster. You may also want to use the same word 
for different purposes, as in the EDITOR. 

Having compiled a program, you may fee! that it is annoying to have to 
recompile it whenever you want to run it. There is no need for that. You 
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can save the whole of the extended dictionary, including the original 
vocabulary, in one operation. 

To do this, you first need to know how much to save, and SIZE will 
provide that information. You then need to alter the locations which hold 
the initialising data, so that the extension of the dictionary will be taken 
into account. 

The first step is to make sure you are not in a special vocabulary, by 
putting in: 

FORTH DEFINITIONS 


Then, as a matter of personal taste, it seems easiest to set HEX , since 
we are dealing with addresses and displacements, which are usually 
more familiar in hexadecimal. 

LATEST holds the name field address of the latest dictionary entry, 
and all searches start from that address, which must be set in 5E4C: 

LATEST OC +ORIGIN ! 
Next, the dictionary pointer must be copied into 5E5C and 5E5E: 


HERE 1C +ORIGIN! 
HERE 1E +ORIGIN! 


lf we want to have our program protected, we must move FENCE to 
the same place: 


HERE FENCE ! 
Finally, we need: 
FORTH 8 + 20 +ORIGIN ! 


This sets up the PFA of the FORTH word, plus 8, in 5E60. 

The amended program can then be saved, using line 9 of the vestigial 
BASIC program, suitably altered to take account of SIZE. After 
verification, the program is ready to be loaded in place of the original 
FORTH tape, when it should perform as it did before saving. 

This technique ts particularly useful if you have created your own pet 
extensions to FORTH for general use. 
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PART VII: 
Programming Techniques 


This part deals with some of the less obvious techniques which can be 
used in writing programs. 





NON-INTEGER ARITHMETIC 


If you find integer arithmetic too limiting, look at the definition of DRAW in 
Appendix A (Dictionary Word No. 447). It works in increments of 
0.0000152. 

The method used is to treat a double number as being scaled by a 
factor of 1/65536. For example, the word LASTY is read from the BASIC 
wordspace, and is then converted into a double number by adding a zero 
lower word — no, not an upper word, a lower word. In integer terms, the 
result is LASTY * 65536 , and this is stored in the double variable Y1. The 
scaled version of LASTX is similarly stored in X1. 

The required position coordinates are then compared with LASTX and 
LASTY — in their unmodified form — to determine how many steps will 
be required to draw the line. it will be either ABS(X — LASTX) or ABS(Y 
— LASTY) , whichever is greater. The nominal increments in the X and Y 
values are then calculated by dividing 65536 times the overall changes 
by the number of steps. M/MOD is used, with alternative routes for 
positive and negative differences, and the results are stored in INCX and 
INCY as double numbers. 

Since both the current x and y values and the related increments have 
been multiplied by 65536, it is valid to add the increments to the original 
values repeatedly, to define the new x and y values, but only the upper 
bytes of x and y need be read, these being the integer parts of the 
numbers. 

This simple but effective approach can be used where the final result is 
required in integer form. If decimal places are wanted, rather more 
complex processes are needed. 
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Fixed point working is fairly straightforward in concept, but involves 
some complications in the details. The scheme is that a fixed number of 
decimal places is adopted, say two. In this case, all numbers will be 
multiplied by 100, as a scaling factor. When a number is input, a decimal 
point will normally be included, and the resulting value of DPL will be 
noted and used to perform any necessary correction. For example, if 
23.02 is input, DPL = 2, and there is no correction. With an input of 23.0, 
on the other hand, a multiplication by ten would be required. 

The modified numbers can be added or subtracted without difficulty, 
since they have the same scaling, but multiply and divide routines must 
be modified. After two numbers have been multiplied together, the result 
must be divided by 100, otherwise that multiplier will be applied twice. 
Before a division, the dividend must be multiplied by 100, or the scaling 
factor will be lost. 

Output of the final result requires only that the decimal point be placed 
in the correct position. 

A wary eye must be kept on possible overflow. A simple multiplication 
of 10 by 20 becomes a multiplication of 1000 by 2000, and the result 
before correction is 2,000,000 , corrected to 20,000. Double numbers will 
Clearly be the rule, and even these will run out of steam with an 
uncorrected result of about 2,000,000,000, giving a corrected value of 
200,000.00. If a scaling factor greater than 100 were used, the limitation 
on maximum value would be increased. 

The answer lies in triple words, which in turn call for a whole new family 
of manipulators and operators. 

Alternatively, a form of floating point can be considered. This will 
inevitably be much slower than integer working, but opens up many 
possibilities. 

A single-precision system can be based on double numbers, with the 
top eight bits reserved as the exponent and the remaining 24 bits serving 
as the mantissa. This corresponds to a typical BASIC single precision 
system. The mantissa is always ‘normalised’ so that its most significant 
bit is true, the exponent being decremented when the mantissa is shifted 
left, and incremented when the mantissa is shifted right. There must be 
two sign bits, one for the exponent and one for the mantissa. Since the 
most significant bit of the mantissa is always 1 in truth, it is sometimes 
used to hold the mantissa sign bit. 

For addition and subtraction, it is necessary to match the exponents of 
the two numbers concerned, by increasing the smaller exponent and 
decreasing the associated exponent. For multiplication, the exponents 
are added and the mantissas multiplied together. In one way and 
another, floating point is complex, and not to be approached light 
heartedly. 

Those who have studied the inner workings of Spectrum BASIC may 
be able to make use of the floating point routines which it contains, but 
the approach to that is much too complex to be studied here. it is worth 
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bearing in mind, however, that the BASIC ROM contains many routines 
that might be incorporated in FORTH if the right technique can be found. 

In particular, access to the exponential and trigonometric functions 
would be appreciated. It is possible to perform such functions in FORTH, 
but only in a relatively crude manner. Square roots may be calculated by 
iterations of: 

Sn = V2(X/S, + S, ) 
where So is an arbitrary value and S,, is an approximation to the square 
root of X. Where S, is too large, it is roughly halved for each iteration. 
Where it is too small, it becomes much larger. As a rough approximation, 
k + 2 iterations will usually produce a reasonably accurate result for 
numbers up to 2k , if Sp is made equal to 2k/4. 

An interesting point arising from this is that trigonometric calculations 
can sometimes be replaced by a technique based on vectors. The idea is 
that x and y coordinates can be combined as a single vector R by the 
expression: 

R?=/a? + b? 

The effective angle can then be expressed by a/b , and this, with R , 
specifies the resultant vector completely. Vectors can be added or 
subtracted by adding or subtracting the a and b values, and it is possible 
by such means to perform such operations as defining a circle — but 
non-integer calculations are essential for that. 


A FINAL PROGRAM 


As a final illustration of some assorted FORTH techniques, here is a final 
fairly large program. It plays three-dimensional noughts and crosses with 
considerable success, though it can be beaten if you know how, and 
have enough concentration to keep a wary eye on what the computer is 
doing. 

Candidly, it is a personal favourite, having been written and rewritten 
for a whole host of computers, including some that were intended for 
rather more serious duties. In machine code, the necessary decisions 
are usually made in a fraction of a second, but in BASIC they may take 
well over a minute. The FORTH version takes about fifteen seconds, 
which is just about acceptable, and is at least five times faster than 
BASIC. 

The reason why so much time is needed is the sheer magnitude of the 
calculations involved. Firstly, the program size is cut down by dispensing 
with the usual table of possible lines within the cubic matrix, and the 
computer is asked to calculate these lines from set rules. For any given 
position, either four or seven lines are involved, and there are sixty-four 
positions. Four entries have to be checked to assess the state of each 
ine. 
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Once the content of a line has been worked out and expressed by a 
code number, the priority level for the line must be looked up and added 
to the total for the position being studied, this being repeated for each line 
passing through that position. Finally, the highest priority must be found. 

The diagram of the display will help to explain some of the variables. 
The numbers 0 to 3 are used for the coordinates, and some players may 
prefer to use 1 to 4, in which case a simple change to the INPROC 
routine will be needed. The numbers are entered in the order VD , VF , 
and VR . The position indicated will be marked on the display, and you 
are given a chance to change your mind before the entry is actually 
made. 


VR=0 1 2 3 
va L VA L 

00 o1 e2 e3 VF =0 VD=0 

o4 05 e6 e7 1 

e8 e9 ©10 o11 2 

e12 e13 014 015 3 
016 o17 e18 019 0 1 

20 e21 O22 023 1 

024 @25 ©26 e27 2 

e28 e29 e30 X31 3 
32 033 034 035 0 2 

036 e37 038 e39 1 

040 o41 042 043 2 

044 e045 046 047 3 
048 049 @50 051 0 3 

052 ©53 054 @55 1 

e56 05/7 058 059 2 

60 e61 e62 063 3 


OX 3 Display Format and Coordinates 
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CH is the position number, used mainly for array reference and for 
marking the latest entry. itis equal to 16* VD + 4* VF + VR. 

Next come four status flags, a temporary hold for priority values, anda 
variable OL which is used in finding the highest priority. 

There are four arrays. AE is a byte array holding the 0 and X entries, 
AP is a word array holding the priorities, AX is a hold for the positions ina 
line, and AW is the priority index, holding the weightings for each line 
configuration, showing the relevant priority. Note how AW is set up, 
rather in the way a BASIC DATA statement is input, but with spaces on 
either side of the commas. 

INIT clears flags and arrays, and DISP puts up the display. POSCAL 
works out the values of VD , VF , and VR corresponding to the value of 
CH , and is used by CURSOR , which marks the latest entry as defined 
by CH, by putting up a reverse video space in OVER mode. As 
CURSOR always follows DISP they are combined as PLAY . 

Two display positions are established by P1 and P2 , and DROP 2 is 
defined to discard 20S. 

The input routines begin with GETN , which waits for a key depression, 
displays the relevant character, and attempts to convert it as a number, 
base ten. Success puts a true flag on TOS, the number on 20S, and the 
input code on 30S. If the input is not numeric, TOS holds a false flag and 
20S holds the code. 

INPOS sets display position P1 and calls GETN . If the flag returned on 
TOS is false, the code then revealed on TOS is checked to see if it is 82 
(‘R’), which calls for a restart. In this case, BE is set, and TOS = 1 to 
make the routine drop out at UNTIL . If the input is numeric, the code is 
dropped by DROP2 . and INPROC is called to obtain the rest of the input, 
checking its validity and offering a chance for a change of mind before 
actually making an O entry. If the 1-4 input range is wanted, instead of 
Q-3, the position calculation in INPROC should be changed to: 


ROT 1 — 16* + 1— SWAP 1 — 4* + DUP AE + C@ 


INPOS repeats until TOS holds 1 when UNTIL is reached. 

Next come the routines which calculate priorities. CALCS3 is called with 
array AX set to the positions in a given line. It checks the contents of each 
position in turn, adding 1 for an ‘O’ entry, 5 for an ‘X’ entry. This produces 
a number characteristic of the line format. For example, a line containing 
OOX. would be given the number 7 . Looking up the seventh entry in AW 
gives a priority of zero, because the line is ‘dead’, containing both O and 
X entries. A line containing OOOO, on the other hand, would have a 
number 4 to represent it, and the fourth entry in AW is again 0, because it 
Is too late to worry about priorities. The game is won. If the line contains 
XXX. its number is 15, and that gives a priority of 896, urging an X entry to 
win. 

In fact, this priority is pre-empted, to save time. If the line number is 15 , 
the empty position is located and filled, and the BX flag is set, so that the 
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X win is declared immediately on return. Similarly, a line with a number 4 
sets BO to declare an O win. 

In general, the priority for the line is added to VP , which accumulates 
the priorities for all lines passing through a particular point. 

CALC2 works out the positions in a line, using data provided by 
CALC1 . Each time CALC2 is called, there are five numbers on the stack 
which express the formula for a given line. For example, a vertical line 
has the formula: 


4*VF + VR + 16*n 
where n = Oto3. 


Since the calculating routines are complex and prone to error in setting 
up the source code, it is useful to define a temporary form of CALC3 as 
follows: 


: CALC3 CR 40D012* AX + ? LOOP ; 


This should be defined after the real CALC3 but before CALC1. It will 
display a list of four or seven sets of positions forming lines for each value 
of CH . This allows a check to be made on the correctness of the line 
selection system. 

An important point about these routines is the use of I’ in CALC2. 
When this routine is called by CALC , an extra entry is put on the Return 
Stack, and it is necessary to dig down to 2ORS to find the loop count. 

The calculating routines are called by CALCP , which scans through 
all the CH values from 0 to 63, checking the priority against each value 
and entering it in array AP. The routine also checks for true states of BO 
and BX, and if either is found the routine drops out, also dropping 
through the subsequent SELECT routine. 

Since CALC3 sets a zero priority for any occupied location, it might 
seem that time could be saved by skipping the call to CALCP for such 
locations. That seems a good idea, but it isn't, because it would mean 
that an OOOO line would never be scanned, and an O win would never 
be found... 

The SELECT routine scans array AP , setting OL to the value read if it 
is the highest yet found, and setting CH to match. Ideally, the scan should 
Start at a random point, and this is simulated by putting 56"VR on the 
stack, but a true random number would be better. When the scan is 
complete, the entry identified by CH is set up. If OL has remained at zero, 
all lines are ‘dead’; and BD = 1 to mark the game as drawn. 

Finally, the overall OX3 routine has to link ali these routines together. 
There are two main loops, one taken for each game, to include INIT, and 
an inner loop for each game turn. After PLAY INPOS , a check is made 
for the end flag BE , and if itis tue CALCP and SELECT are skipped. The 
CASE structure is used to check the four flags, issue reports, and alter 
the stack values to determine whether the inner or outer loop should be 
taken. 
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No FORTH program is ever perfect, and this one is no exception. It has 
been used to make a number of special points, and you may enjoy 
attempting to improve it. In that case, spread it out well in the screens, to 
make changes easy, but don't be too generous. You have 150 lines in ten 
screens, and as laid out here you would need about 190 lines. You could 
use two sets of screens, but that could be inconvenient. 


A Three-Dimensional Noughts and Crosses Program 


( OX3 ) 

- TASK ; 

O VARIABLE VR (Left to right coordinate) 
QO VARIABLE VF (Back to front coordinate) 
QO VARIABLE VD (Top to bottom coordinate) 
O VARIABLE CH (Position number) 

O VARIABLE BO (O WIN flag) 

O VARIABLE BD (DRAW flag) 

QO VARIABLE BE (End flag) 

O VARIABLE BX (X WIN flag) 

O VARIABLE VP (Priority hold) 

QO VARIABLE OL (Highest priority found) 
O VARIABLE AE 62 ALLOT (Play state array) 

O VARIABLE AP 126 ALLOT (Priority array) 

O VARIABLE AX 6 ALLOT (Line definition array) 

1 VARIABLE 


AW 2, 16,256,0,4,0,0,0,0,32,0,0,0,0, 


896 ,0 ,0,0,0,0,0,0, (Priority basis) 
: INIT AE 64 ERASE AP 128 ERASE 
Oo BO !0 BD!0 BE!0 BX !: (Clear arrays, flags) 
: DISP CLS040DO (Display state of play) 
4 0 DO 
CR 4 1 -— 2 * SPACES 
40 DO 
DUP AE + C@ DUP 
IF EMIT 
ELSE .” .” DROP 
ENDIF 
SPACE SPACE 
LOOP 
LOOP CR 
LOOP ; 


: POSCAL CH @ 16 /MOD VD ! 4 /MOD VF ! VR ! ; 


: CURSOR POSCAL VD @ 5* VF @ + 1+ = (Vertical position) 
VR @3* VF @2* -8 
(Horizontal position) 
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AT 1 GOVER 2 INK 
(Position cursor) 
. B@’ O GOVER 0 INK ; 


: PLAY DISP CURSOR ; 


° P19 18 AT ; (Text position 1) 
; P2 210 AT ; (Text position 2) 
; DROP2 SWAP DROP ; (Drop 20S) 
: GETN KEY DUP EMIT DUP 10 DIGIT ; 
(Get a digit) 
: INPROC GETN 
IF DROP 2 GETN (If numeric discard code) 


IF DROP2 


(If numeric discard code) 


ROT 16 * + SWAP 
4 * + DUP AE + C@ (Calculate position, check) 
IF P2 .” Position Taken ” 


ELSE CH ! PLAY P2 
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(If free, set CH, display) 


. Is that right? ” 
KEY 89 — O= (Leave 0 if entry not good) 
ENDIF DUP (Duplicate flag) 
IF 7QAECH@+C! (If 1make 0 entry) 
P220SPACES (and clear message) 
ENDIF 
ELSE 0 (Not numeric. Leave 0) 
ENDIF 
ELSE 0 (Not numeric. Leave 0) 
ENDIF : 
: INPOS BEGIN 
P1 GETN 
IF DROP2 INPROC __ (If numeric discard code) 
ELSE 82 — 0= (Else check for ‘R’) 
IF 1 BE! 1 (If ‘R’ set BE. TOS = 1) 
ENDIF 1 (If other letter TOS = 1) 
ENDIF 
UNTIL ; (Repeat if TOS = 0) 
- CALC3 0 4 0 DO 
|2* AX + @ (Read position number) 
AE + C@ (Read contents) 
79 — 0= (Check for ‘O’) 
IF SWAP 1+ SWAP _ (if‘O’ increment TOS) 
ENDIF 
88 — 0= (Check for ‘X’) 
IF 5+ (If °X’ add 5) 
ENDIF 
LOOP (Line key number on TOS) 


AE CH @ + C@ 0= (Is position CH free?) 
IF DUP2*AW+ @VP +! (Ifso, add priority to VP) 


ENDIF 
DUP 4 —- Q= (Check for OOOO line) 
IF 1 BO! (lf 0000 set BO) 
ENDIF 
15 —0= (Check for XXX. line) 
IF80DO (If XXX. identify free position) 
| AX + @ AE + C@ 0= 
IF AX1+ @ CH! (If free set CH) 
99 CH @ AE + C! (and enter ‘X’) 
ENDIF 
2+LOOP 
1 BX! (Set BX) 
ENDIF ; 
* CALC2 VD @ * SWAP (Calculate position) 
VF @ * + SWAP 
VR @ * + SWAP 
y+ + 
AXI'+2* +1; 


; CALC1 POSCAL 

40D00 104 16 CALC2 LOOP CALC3 

40D00410 16 CALC2 LOOP CALC3 

40D00 16 140 CALC2 LOOP CALC3 

VF @ VR @ —- 0= 

lIF40D0O0500 16 CALC2 LOOP CALC3 
VD @ VF @ —- 0= 
IF40D0021000CALC2 LOOP CALC3 
FNDIF 

ENDIF 

VD @ VR @ — 0= 

IF40D0 17040 CALC2 LOOP CALC3 
VD @ VF @+3-0— 
IF 40 DO 12 130 0 0 CALC2 LOOP CALC3 
ENDIF 

ENDIF 

VD @ VF @ — 0= 

lIF40D0020 100 CALC2 LOOP CALC3 
VD@VR@+3-0= 
IF40D03 19000 CALC2 LOOP CALC3 
ENDIF 

ENDIF 

VD @VR@ +3 —-0= 

IF40DO3 15040 CALC2 LOOP CALC3 
VF @ VR@ — 0= 
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IF 40 DO 15 11000 CALC2 LOOP CALC3 


ENDIF 
ENDIF 
VF @VR@+3-0= 


IF40DO3300 16 CALC2 LOOP CALC3 


ENDIF 
VD @ VF @+3-0= 


IF 40 DO 12 12 100 CALC2 LOOP CALC3 


ENDIF ; 
> CALCP 10CH!O VP! 
BEGIN 

CALC1 BO @ 0= 


(TOS = 1,CH = 0,VP = 0) 


(Calculate priority) 


IF VP @APCH@2 * + !(IfBO = Osetpriority in AP) 


OVP! 
BX @ 
IF DROP 0 64 


(Zero VP) 
(If BX = 1 change flag to) 
(1 and set endcount.) 


ELSE CH @ DUP 1 + CHI(Increment CH, leave copy) 


ENDIF 
64 -— 0= 
ELSE DROP 01 
ENDIF 
UNTIL ; 


- SELECT BEGIN WHILE 
OOL! 
VR @ 56" 
640 DO 
2+ 128 MOD 
DUP AP + @OL@ > 
IF DUP AP + @ OL! 
DUP 2/CH! 
ENDIF 
LOOP 
88 CH @ AE + C! 
DROP 0 
REPEAT 
OL @ 0= 
IF 1BD! 
ENDIF ; 
- OX3 BEGIN INIT 
BEGIN PLAY INPOS 
BE @ 0= 
IF CALCP SELECT 
ENDIF 
O0O0P2 


(If CH = 64 leave 1) 

(If BO = 1 change stack) 

(lf TOS = 0 repeat, else exit) 
(with flag for SELECT) 

(Drop through if TOS = 0) 
(Zero ‘highest priority’) 
(Quasi random number) 


(Advance pointer on stack) 
(Compare AP(n) with OL) 

(If AP(n) greater, OL = AP(n)) 
{and set CH from TOS) 


(Set chosen ‘X’ entry) 
(Ensure no repeat) 


(If OL =0 set BD) 


(Game loop point) 
(Make plav) 

(Check e. .d flag) 

(if BE = 0, find X move) 


(CASE condition = 0) 


CASE BE @ 0= OF 


DROP 1 ENDOF 
BD @ 0= OF 

.” Drawn Game 
DROP 1 ENDOF 
BO @ 0= OF 

.’ OWins 
DROP 1 ENDOF 
BX @ 0= OF 
PLAY .” X Wins 
DROP 1 ENDOF 


ENDCASE 


UNTIL 


P1.” Another run ?” KEY 89 — 


UNTIL ; 


(If BE = 1 TOS = 1) 


" (If BD = 1 report draw) 
(and TOS = 1) 


” (lf BO = 1 report O Win) 
(and TOS = 1) 


” (If BX = 1 report) 
(with display. TOS = 1) 
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APPENDIX A: 
The Dictionary 


The contents of the Abersoft FORTH dictionary are defined in 
condensed form. Machine code sections are expressed in pseudo-code 
related to Z80 processor functions. Parameter Fields are translated from 
Code Field addresses to word names. A particular entry can be located 
through reference to the link list in the main index. 

The Z80 registers are used as follows: 


BC holds the Instruction Pointer (IP), which gives the address of the 
next link to be implemented. 


DE is used to hold data to be put on the stack where more than one 
word is to be pushed. (The FORTH W register) It also holds 
incremental values and jump spans. 


HL is used to hold data to be put on the stack, its contents being 
pushed after the contents of DE where two words are stacked. 


IX holds the user area pointer. 
SP is the stack pointer. 


These are the special uses of the registers. All registers may be called 
into service for other purposes as necessary. 

The dictionary definition is not easy to follow, because there are so 
many cross-references, but this is unavoidable. Examination of some of 
the more complex functions will often suggest useful formats for new 
words. 

It is useful to remember that a word must be defined before it can be 
used in a further definition, so the constituents of a definition will always 
occur before the definition itself. 

The FORTH program begins with a number of variables and 
constants. While these are not strictly part of the dictionary, they are 
needed to understand how some dictionary functions operate. 
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5E06 
5E08 
SEOA 
5E0C 
5SEOE 
5E10 
5E12 
9E14 
5E16 
5E 18 
SETA 
5E1C 
SEITE 
9E20 
5E22 
5E24 
5E26 
9E28 
SE2A 
5E2C 
SE2E 
9E30 
SE32 
9E34 
9E36 
5E38 
SESA 
5SE3C 
5ESE 
5E40 
5E41 
5E44 
9E45 
5E48 
DE4A 
5E4C 
SESE 
SE50 
9E52 
9E54 
5E56 
5E58 
SES5A 
SE5C 
SE5E 
SE60 
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RO 

TIB 
WIDTH 
WARNING 
FENCE 
DP 
VOC-LINK 
BLK 

IN 

OUT 

SCR 
OFFSET 
CONTEXT 
CURRENT 
STATE 
BASE 
DPL 

FLD 

CSP 

R# 

HLD 


00 
C3 BO 6D 


C3 93 6D 
0101 
00 OE 
49 81 
OC 00 
66 5E 
CB40 
CBEO 
CB40 
001F 
0000 
8159 
8159 
77AC 


Initial Stack Pointer Contents 
Initial Return Stack Pointer Contents 
Address of Terminal Input Buffer 
Maximum word length 

Message control flag 

Dictionary protection limit 
Dictionary Pointer 

Vocabulary search start address 
Block number 

Text buffer pointer 

Output pointer 

Last used screen 

Block offset 

Dictionary start address 
Dictionary start address 

System mode 

Number representation base 
Decimal point location 

Unused 

Stack pointer hold 

Editing cursor, etc. 

Address of last character in output 


Entry jump to COLD at 6DBO 


Entry jump to WARM at 6D93 


Initial value for 5EO6 
5E08 
5EOA 
5E0C 
5E0OE 
5E10 
5E12 
5E14 
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5E62 


5E64 
5E66 5E00 Source for IX 
5E68 Return stack pointer 


The dictionary proper now begins. To cover possible modifications, 
the entry points are defined by link numbers rather than by addresses, 
but the actual addresses can be determined quite simply with the aid of 
—FIND . Entries marked * execute even in compile mode. 


1 PUSHDE Push the contents of DE on to the stack 
2 PUSHHL Push the contents of HL on to the stack 
3 NEXT1 HL = BC. BC = BC + 2 

4 NEXT2 HL = (HL). Go to (HL). 


Where, as above, the entries are closely spaced, they run on to the 
subsequent entry. PUSHDE and PUSHHL are used on return from 
other modules to set data on to the calculation stack, and then the 
interpretive pointer IP (held in BC) is used to look up the next link, to 
which the routine jumps. IP is incremented to point to the link for the 
next action. This is the central control of the whole FORTH system. 
5 LIT HL = (BC). BC = BC + 2. Go to PUSHHL. 
The word stored in the location pair following the LIT link is read into 
HL and pushed on to the calculation stack. LIT, in effect, identifies 
the word as data, not a link. 
6 EXECUTE POP HL. Go to NEXT2 


TOS is popped into HL as a link to a routine to be executed. 


7 BRANCH HL = BC. DE = (HL). HL = HL+DE. BC = HL. 
Go to NEXT 1. 
The word stored in the location pair following BRANCH is added to 
the IP, interpretation being resumed at the resulting address. 
8 OBRANCH POP HL. If HL = 0 go to BRANCH. 
Else BC = BC + 2. Go to NEXT1. 
This is the conditional branch, performed only if TOS = 0. 
Otherwise, the branch span word is skipped by advancing the IP. 
9 (LOOP) DE = 1 
10 HL = (RSP). (HL) = (HL) + DE. DE = (HL) 
HL = HL + 2. lf D was negative, go to 11. 
Else set sign flag on DE — (HL). Go to 12 
11 Set sign flag on (HL) — DE. 
12 If negative go to BRANCH. 
Else HL = HL + 2. (RSP) = HL 
BC = BC + 2. Goto NEXT1. 
This is the compiled form of LOOP. HL reads the Return Stack 
Pointer, and DE is added to TORS. 2ORS is then compared with 
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13 


14 


15 


16 


17 


18 


19 
20 


21 


22 
23 


TORS, taking the sign of DE into account. (See (+ LOOP) below.) If 
the index in TORS has neither reached nor passed the limit value in 
2ORS, BRANCH is entered to loop back to immedately after (DO), 
the necessary jump span being calculated at compile time. 
Otherwise the RSP is set back two words, effectively discarding the 
two relevant entries. The IP skips the branch span data, and 
NEXT 1 continues the action. 

(+LOOP) POP DE. Go to 10. 


Instead of being set to 1, as for (LOOP), DE is set from TOS, and 
(LOOP) follows. 
(DO) (RSP) = (RSP) — 4. POP DE. HL = (RSP) 

(HL) = DE. POP DE. HL = HL + 2 

(HL) = DE. Go to NEXT 1. 
This is the compiled form of DO. Two new entries are added to the 
Return Stack. The new TORS is set from TOS (initial index value) 
and the new 2ORS is set from 20S (limit index value). 
| HL = (RSP). DE = (HL). PUSH DE. Go to NEXT1. 
The contents of TORS are copied to TOS. Within a DO loop, this 
transfers to the current index value. 
DIGIT POP HL. POP DE. A= E —48 

lf A is negative go to 18. 

Else if Ais less than 10 go to 17. 

A=A-7. 

If Ais less than 10 go to 18. 

lf Ais greater than L go to 18. 

E = A. HL = 1. Go to PUSHDE. 

L =H. GOTO PUSHHL. 
The number base from TOS is popped into HL. The ASCII code in 
2QOS is popped into DE. The code is converted to a numeric value. If 
that value is negative, greater than number base or otherwise 
invalid, 18 is reached. A zero is pushed as TOS. (It is assumed that 
the number base does not exceed 255, so H = 0). Otherwise, the 
number is pushed as 20S, with TOS = 1 to indicate successful 
conversion. 
(FIND) POP DE. 

POP HL. PUSH HL. 

If (DE) XOR (HL) AND 3FH +0 go to 26. 

INC HL. INC DE. 

lf (DE) XOR (HL) 40 go to 25. 

If bit 7 of (DE) XOR (HL) = O goto 21. 

HL =DE+5 

Exchange (SP) and HL 

DEC DE. 
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24 


25 
26 
27 


28 


29 


30 


31 


A = (DE). If bit 7 of A = 0 goto 23. 

E = A.D = 0. HL = 1. Go to PUSHDE. 

If (DE) XOR (HL) = 1 goto 27. 

INC DE. A = (DE). If bit 7 of A= 0 go to 26. 
INC DE. Exchange DE and HL. DE = (HL) 
lf DE + 0 goto 20. 

Else POP HL. HL = 0. Go to PUSHHL. 


This is a search routine looking for a match to text pointed to by 
20S, the search starting at TOS. The reference text is a word 
name, and the routine searches through the dictionary name fields. 
The search pointer is popped into DE, and the reference text 
pointer is popped into HL and then restored. If the codes (length 
bytes) pointed to are unequal in respect of bits 0-5 , the routine 
jumps on to 26. (Note that the SMUDGE bit is not taken into 
account.) 


Otherwise, the pointers are advanced. The routine loops through 
21 until either a mismatch is found or bit 7 of (DE) is found, marking 
the end of the dictionary name. In the latter case HL = DE + 5, so 
that HL points to the Parameter Field Address, and this is put on to 
the stack in exchange for the reference text pointer. DE is then 
repeatedly decremented until the length byte of the dictionary entry 
is found, and the length byte is then pushed on to the calculation 
stack, followed by a true flag. 
lf a character mismatch is found, 25 is reached. If bit 7 of the 
dictionary name had bit 7 set, the routine skips on to 27. Otherwise, 
and if a length byte mismatch brings the routine to 26, DE is 
repeatedly incremented until (DE) has bit 7 set. One more 
increment sets DE pointing to the Link Field Address. The link is 
read, and if it is not zero the routine loops back to 20. If the link is 
zero, the end of the dictionary has been reached, and TOS is 
replaced by a zero (false) flag to show that no match was found. 
ENCLOSE POP DE. POP HL. PUSH HL. 
A=E.D=A.E=FFH. DEC HL. 


INC HL. INC E. if (HL) = Ago to 29 
D = 0. PUSH DE. D = A. A = (HL) 


lf A #0 go to 30. 

Else D = 0. INC E. PUSH DE.DEC E. PUSH DE. 
Go to NEXT1. 

A = D. INC HL. INC E. If A = (HL) goto 31. 

If (HL) 40 go to 30. 


D = 0. PUSH DE. PUSH DE. Go to NEXT1. 
D = 0. PUSH DE. INC E. PUSH DE. Go to NEXT1. 


This routine scans text to locate delimiters. The delimiter is popped 
from TOS into DE, the start address for the scan is popped from 


93 


32 
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34 
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37 


38 


39 
40 


41 


42 


20S into HL, and restored. The delimiter code is copied into A and 
D. Eis set to — 1 and HL is set back. A loop through 29 then seeks 
the first non-delimiter character, advancing HL and E. When the 
loop drops out, D = O and DE is pushed. (Offset to first non- 
delimiter character in 30S) If (HL) = 0, E + 1 is pushed (offset to 
next delimiter in 2OS) and then E is pushed (offset to first character 
not included in TOS). 


lf (HL) 40, aloop through 30 scans the text until a delimiter is found 


(go to 31) or (HL) = 0. In the first case the values pushed are E and 
E+1. Inthe second case E Is pushed twice. 


EMIT Machine code at 274 is called 
OUT +! OUT is incremented. 
KEY Machine code at 266 is called. 


For details, see the machine code routines. 


?TERMINAL ~~ HL =O. Machine code at 263 is called. 

CR Machine code at 276 is called. 

CMOVE HL = BC. POP BC. POP DE. Exchange (SP),HL 
if BC = 0 go to 37 
Else LDIR. POP BC. 
Go to NEXT 1. 


LDIR performs the copy action, but BC is needed to hold the length 
parameter, so the IP passes to HL, then to the stack, and back to 
BC when LDIR has been executed. 
U* POP DE. POP HL. PUSH BC. 

B=H.A=L.CALL39 

PUSH HL. H = A.A=B.B=H. CALL 99. 

POP DE. C = D. HL = HL + BC.A=A + carry. 

D=L.L=H.H=A. POP BC. PUSH DE. 

Go to PUSHHL. 

HL=0.C=8 

HL = 2*HL. RLA. If no carry go to 41. 

HL = HL + DE.A=A+ carry. 

DEC C. IF C #0 goto 40. 

RETURN. 
The subroutine at 39 multiplies A by DE, with the result in HL. It is 
first used to multiply the lower byte of 2OS by TOS, then to multiply 
the upper byte of 2OS by TOS. The two results are combined as a 
double number, the lower half pushed from DE, the upper half from 
HL. Note that here, again, the IP is saved on the stack to make BC 
available for other use. 
U/MOD HL = 4+ SP. E = (HL). (HL) =C 

INC HL. D = (HL). (HL) = B. POP BC. POP HL. 
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04 
95 


56 
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if BC is greater than HL go to 43. 

Else HL = FFFFH. DE = FFFFH. Goto 48. 
A= 16 

HL = 2*HL RLA. Exchange DE and HL. 
HL = 2*HL. If no carry go to 45. 


INC DE. AND A. 

Exchange DE and HL. RR A. PUSH AF. 
If no carry go to 46. 

A = AANDL. HL = HL — BC —- carry 
Go to 47. 


HL = HL — BC. tf no carry go to 47. 
HL = HL + BC. DEC DE 


INC DE. POP AF. DEC A. If A 40 go to 44. 
POP BC. PUSH HL. PUSH DE. Go to NEXT1 


When data is pushed on to the Z80 stack, the stack pointer is left 
pointing to the last-entered byte. Adding four to the SP therefore 
points to the high byte of 30S. This is taken into DE, and replaced 
by the IP from BC. TOS is taken into BC, and 20S into HL. The 
routine divides 20S/30S by TOS. If TOS is not greater than 2OS, 
FFFFH is pushed on to the stack twice. Otherwise, an iterative 
division routine is performed on a restoring basis, which leaves a 
true remainder. This is pushed from HL, the result from DE. 


AND POP DE. POP HL. HL = HL AND DE. 
Go to PUSHHL. 
OR POP DE. POP HL. HL = HL OR DE. 
Go to PUSHHL. 
XOR POP DE. POP HL. HL = HL XOR DE. 
Go to PUSHHL. 
SP@ HL = SP. Go to PUSHHL 
SP! DE = (IX + 6). Exchange DE,HL. SP = HL. 
Go to NEXT 1 


IX points to 5E40 (See COLD) and is used to access the variable 
area. 


RP@ HL = (RSP). Go to PUSHHL. 

RP! DE = (IX + 8). Exchange DE,HL. (RSP) = HL. 
Go to NEXT1. 

‘S HL = (RSP). BC = (HL). HL = HL + 2. 


(RSP) = HL. Go to NEXT1. 


This key function terminates interpretation of a colon definition or a 
screen. The IP is recovered from the Return Stack. 


LEAVE HL = (RSP). DE = (HL). HL = HL + 2. 
(HL) = DE. Go to NEXT1. 


Used within a DO LOOP, LEAVE copies the current index value to 


95 


98 


99 


60 


61 


62 


63 


64 
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73 


74 
75 
76 


77 


the limit entry so that the loop will drop out at the next LOOP. 


>R POP DE. HL = (RSP). (HL) = DE. HL = HL — 2 
(RSP) = HL. Go to NEXT1 
R> HL = (RSP). DE = (HL). HL = HL + 2 


(RSP) = HL. PUSHDE. Go to NEXT1. 


These two transfer data between TOS and TORS, adjusting the 
stacks. The next function copies TORS to TOS without changing 
TORS. 


R Go to 15 

R is identical in action to |. 

O= POP HL. If HL = 0 then HL = 1, else HL = 0. 
Go to PUSHHL. 

O0< POP HL. HL = 2*HL. If no carry HL = 0, 
else HL = 1. Go to PUSHHL. 

+ POP DE. POP HL. HL = HL + DE. 
Go to PUSHHL. 

D+ HL = SP + 6. DE = (HL). (HL) = BC. 


POP BC. POP HL. HL = HL + DE. 
Exchange DE,HL. POP HL. 

HL = HL + BC + carry. 

POP BC. PUSH DE. Go to PUSHHL. 


The IP is saved on the stack in place of 40S. Two separate 
additions are used to add two double numbers together. 


MINUS POP DE. HL = 0 — DE. Go to PUSHHL. 
DMINUS POP HL. POP DE. DE = 0 — DE. 
HL = 0 — HL — carry. PUSH DE. Go to PUSHHL. 
OVER POP DE. POP HL. PUSH HL. Go to PUSHDE. 
DROP POP HL. Go to NEXT1. 
SWAP POP HL. Exchange (SP) and HL. Go to PUSHHL. 
DUP POP HL. PUSH HL. Go to PUSHHL. 
2DUP POP HL. POP DE. PUSH DE. PUSH HL. 
Go to PUSHDE. 
+1 POP HL. POP DE. (HL) = (HL) + E. INC HL. 
(HL) = (HL) + D + carry. Go to NEXT1. 
TOGGLE POP DE. POP HL. (HL) = (HL) XOR E 
Go to NEXT 1. 
@ POP HL. DE = (HL). PUSH DE. Go to NEXT1. 
C@ POP HL. L = (HL). H = 0. Go to PUSHHL. 
2@ POP HL. HL = HL + 2. DE = (HL). PUSH DE. 


HL = HL — 2. DE = (HL). PUSH DE. Goto NEXT1. 
! POP HL. POP DE. (HL) = DE. Go to NEXT1. 
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84 


85 


86 


87 


88 


89 


Cc! POP HL. POP DE. (HL) = E. Go to NEXT1. 


2! POP HL. POP DE. (HL) = DE. POP DE. 
HL = HL + 2. (HL) = DE. Go to NEXT1. 
7EXEC Error if not executing 
ICSP Save stack pointer in CSP 
CURRENT @ 
CONTEXT! CONTEXT = CURRENT 
CREATE Create a dictionary heading. 
] Resume compilation 
(;CODE) Point to following code. (81) 


HL = (RSP). (HL) = BC. 

HL = HL — 2. (RSP) = HL. 

INC DE. BC = DE. 
This is another key routine. Execution of colon performs the checks 
shown above, then sets up a link to 81. The IP then interprets the 
words which follow, setting up links or data words to represent 
them. This forms the parameter field of the new dictionary entry. 
The process is terminated by semicolon, below: 


?CSP Error if SP # CSP. 
COMPILE Compile link into dictionary. 
‘S 


SMUDGE Restore the SMUDGE bit. 

[ Suspend compilation. 
Note that colon and semi-colon arise only in an execution context, 
colon switching to compilation and semi-colon restoring 
execution. 


NOOP NOOP does nothing, except to go 
to NEXT 1. 
CONSTANT CREATE Create a dictionary entry. 


SMUDGE Toggle the SMUDGE bit. 
; (Comma) Store TOS indictionary. 
(;CODE) Point to following code. 
INC DE. Exchange DE,HL. 
DE = (HL) PUSH DE. 
Go to NEXT1. 
CONSTANT creates a dictionary entry which refers to the code at 
85. This picks up the following word and puts it on TOS. 
VARIABLE CONSTANT Create aconstant entry. 
(;CODE) Point to following code. 
INC DE. PUSH DE. Goto NEXT1. 
The code at 87 puts the address of a variable on the stack. 
USER CONSTANT Create aconstant entry. 
(;CODE) Point to following code. 
HL = IX + DE. Go to PUSHHL. 
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99 


100 
101 
102 
103 
105 
106 
107 
108 
109 
110 
1117 
112 
113 
114 
115 
116 
117 
118 
119 
120 


A variable in the general workspace is referenced, using IX and a 
single byte displacement picked up in E. The address of the 


variable goes on TOS. 
0 

1 

2 

3 

BL 


C/L 
FIRST 
LIMIT 
B/BUF 


B/SCR 


The above use the code at 85. 


+ ORIGIN LIT 5E40 + 


WIDTH 
WARNING 
FENCE 
DP 
VOC-LINK 
BLK 

IN 

OUT 

SCR 
OFFSET 
CONTEXT 
CURRENT 
STATE 
BASE 

DPL 

FLD 
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Constant 0 to TOS 

Constant 1 to TOS 

Constant 2 to TOS 

Constant 3 to TOS 

Constant 20H (Space code) 
to TOS 

Constant 40H (Characters per 
line) to TOS 

Constant CBEOH (1st buffer 
start) to TOS 

Constant DOOOH (Last buffer 
end) to TOS 

Constant 8OH (Bytes per buffer) 
to TOS 
Constant 8 (Blocks per screen) 
to TOS 


Add 5E40 (nominal origin) to TOS 


Address 5E06 to TOS 
Address 5E08 to TOS 
Address 5E0A to TOS 
Address 5E0C to TOS 
Address 5E0E to TOS 
Address 5E10 to TOS 
Address 5E12 to TOS 
Address 5E14 to TOS 
Address 5E16 to TOS 
Address 5E18 to TOS 
Address 5E1A to TOS 
Address 5E1C to TOS 
Address 5E1E to TOS 
Address 5E20 to TOS 
Address 5E22 to TOS 
Address 5E24 to TOS 
Address 5E26 to TOS 
Address 5E28 to TOS 
Address 5E2A to TOS 


121 
122 
123 


124 
125 
126 
127 
128 


129 


130 


131 
132 


133 


134 
135 


136 


137 
138 


139 
140 


CSP Address 5E2C to TOS 
R# Address 5E2E to TOS 
HLD Address 5E30 to TOS 
The above use the code at 89. 
1+ 1+ Add 1 to TOS 
2+ 2+ Add 2 to TOS 
HERE DP @ Read dictionary pointer to TOS. 
ALLOT DP +! Add TOS to dictionary pointer. 
: HERE !2ALLOT Store TOS at HERE, add 2 to DP. 
(Comma) 
C, HERE C! Store byte of TOS at HERE, 
1 ALLOT DP = DP + 2. 
— POP DE. POP HL. 
HL = HL — DE. Go to PUSHHL. 
= — Q= lf TOS = 20S, TOS = 1 else 0. 
< POP DE. POP HL. If bit 7 of 
D XORH = Othen HL = HL — DE 
(signs differ) If H is positive then 
HL = O else 1. Go to PUSHHL. 
U< 2DUP XOR 0< If signs of TOS,2OS differ set 
true flag. 
OBRANCH 
000C lf false flag go to 134. 
DROP Discard TOS 
0< 0= Set true flag if new TOS positive. 
BRANCH 0006 End. 
— 0< Set true flag if TOS exceeds 20S. 
> SWAP < Exchange TOS,2QOS and perform 
reverse function. 
ROT POP DE. POP HL. 
Exchange (SP), HL. 
SPACE BL EMIT Output a space. 
—DUP DUP Duplicate TOS 
OBRANCH 
0004 End if TOS =0 
DUP Duplicate TOS 
TRAVERSE SWAP stack: n address. (n = + 1) 
OVER + Stack: n addresstn 
LIT OO7F 
OVER Stack: n addresst n 7FH 
addresst n 
C@ < Compare (address tn) with 7FH. 
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141 
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145 


146 


147 


148 


149 


150 


151 


152 


153 


154 


OBRANCH 
FFFO 


SWAP DROP 


If (address+ n) not greater than 
7FH go to 140. 

Else discard n, leaving 

address tn. 


This scans through a dictionary name field in a direction 
determined by the sign of n, until a byte with bit 7 true is found. 
CURRENT @ @ TOS = (CURRENT) 


LATEST 
LFA 
CFA 
NFA 


PFA 
ICSP 


?7ERROR 


?COMP 


?7EXEC 


?PAIRS 


?CSP 


?7LOADING 


COMPILE 


LIT 0004 — 
2 

LIT 0005 — 
LIT FFFF 


TRAVERSE 
1 TRAVERSE 


LIT 0005 + 
SP@ 
CSP! 
SWAP 
OBRANCH 
0008 
ERROR 


BRANCH 0004 


DROP 


STATE @ 0= 


LIT 0011 
?7ERROR 
STATE @ 
LIT 0012 
?7ERROR 


LIT 0013 
?7ERROR 


SP@ CSP @ — 


LIT 0014 
?7ERROR 
BLK @ 0= 
LIT 0016 
?7ERROR 


?COMP 
R> 
DUP 2+ 
>R 


100 


Subiract 4 from TOS. 

Subtract 2 from TOS. 

Subtract 5 from TOS. 

TOS = — 1. 

Scan back through name field. 
Scan forward through name field. 
Add 5 to TOS. 
Read stack pointer 
Write to CSP. 


Stack: n flag 


if flag zero go to 148. 
Report error 

End 

Discard error number. 
True flag on TOS if STATE = 0 
Error number 17 

Report error if flag true. 
False flag if STATE = 0 
Error number 18 

Report error if flag true. 
False flag if TOS = 20S 
Error number 19 

Report error if flag true. 
Compare SP with CSP. 
False flag if equal. 

Error number 20 

Report error if flag true. 
True flag on TOS if TIB in use. 
Error number 22 

Report error if flag true. 
Error if not compiling. 
TORS to TOS 

Stack: TORS TORS+2 
TOS to TORS 


“155 
156 ] 


157 SMUDGE 


158 HEX 
159 DECIMAL 


160 (;CODE) 


*161 ;CODE 


162 <BUILDS 
163 DOES> 


164 


@, 

O STATE! 
LIT OOCO 
STATE ! 
LATEST 
LIT 0020 
TOGGLE 
LIT 0010 
BASE ! 
LIT OOOA 
BASE |! 
R> 
LATEST 
PFA CFA |! 


?CSP 
COMPILE 
(;CODE) 


SMUDGE 
0 CONSTANT 


R> 
LATEST PFA! 


(,;CODE) 


Store (TORS) at HERE 
Set STATE = 0 


Set state = 192 


Toggle bit 5 of LATEST. 
Set BASE = 16 


Set BASE = 10 
TORS to TOS 


Write TORS to LATEST 
code field. 


Check that SP = CSP 


Compile (; CODE) 

Set STATE = 0 

Toggle bit 5 of LATEST 
Constant entry established. 
TORS to TOS 

Copy to parameter field of 
LATEST 

Link to following code. 


HL = (RSP) — 2. (HL) = BC. 
(RSP) = HLINC DE. 
Exchange DE,HL. BC = (HL) 
Go to PUSHHL. 


The IP is put on the return stack and re-initialised from (DE-+ 1), 
while DE + 1 goes onto TOS. 


165 COUNT 


DUP 1+ 


SWAP C@ 


Stack: addr addr+ 1 
Stack: addr+ 1 (addr) 


The stack initially holds the address of the length byte of a text 
string. The address of the start of the text is put on 20S with the 
length byte on TOS. 


166 TYPE 


—DUP 
OBRANCH 
0018 
OVER + 
SWAP 
(DO) 


101 


Duplicate TOS if non-zero 


Branch to 168 if TOS = 0 
Stack: addr addr+ 1length 
Stack: addr+length addr 


167 


168 
169 —TRAILING 


170 


171 
172 


IC@ 

EMIT 

(LOOP) FFFB 
BRANCH 0004 
DROP 

DUP 0 

(DO) 

OVER OVER 
+1- 


C@ BL — 


OBRANCH 
0008 

LEAVE 
BRANCH 0006 
1- 

(LOOP) FFEO 


Read (I) to TOS 
Print TOS 

Loop to 167 

End 

Discard address 


Stack: addr length length 0 


Stack: addr length addr length 
Stack: addr length 
addr+length— 1 

Compare (addr+length— 1) 
with space code 


Go to 171 if match found. 
Set loop exit condition. 
Go to 172 

Decrement length 

Loop to 170. 


A text string is scanned backwards, the length byte being 
decremented for each space code found, until a non-space code 


appears. 
173 (.”) 


R 
COUNT 
DUP 1+ 
R>+ >R 
TYPE 


TORS copied to TOS 

Adjust address and length 
Stack: addr length length-+ 1 
TORS = TORS + length + 1 
Output string. 


TORS is updated and the string defined is output. 


"174. 


175 


LIT 0022 
STATE @ 
OBRANCH 
0014 
COMPILE (.”) 
WORD 
HERE C@ 
1+ ALLOT 


Code for ”’ (delimiter) 
TOS = STATE 


lf executing go to 175. 
Store text at HERE 


Read length byte 
Reserve length + 1 bytes. 


BRANCH 000A End 


WORD 
HERE 
COUNT TYPE 


Store text at HERE 


Output text 


This word acts quite differently in execute mode and compile mode. 
In compile it sets up (.”) with the text. In execute it outputs the text. 


OVER + OVER Stack: addr addr-+ limit addr 


176 EXPECT 


(DO) 


102 


177 KEY DUP Stack: addr input input 


LIT OOOE 
+ORIGIN@ TOS = (5E4E) 
= Zero flag if TOS + input 
OBRANCH 
002A lf zero flag go to 179. 
DROP DUP | = Zero flag if | + addr. 
DUP Duplicate flag 
R>2—-+>R TORS = TORS — 2 + flag 
OBRANCH 
OOOA lf flag zero go to 178 
NOOP NOOP Delay ? 
178 BRANCH 0008 Code for cursor left. 
BRANCH 0028 Go to 182 
179 DUP Stack: addr input input 
LIT OOOD Newline code 
= Zero flag if input + newline. 
OBRANCH 
OOOE If zero flag go to 180 
LEAVE Terminate loop 
DROP BL 0 Stack: addr space-code, zero. 
BRANCH 0004 Goto 181 
180 DUP Stack: addr input input 
181 |C! Store input in (I) 
Oli+! Zero next location. 
182 EMIT Output TOS 
183 (LOOP) FF9C Loop to 177 
DROP Clear stack, end. 
184 QUERY TIB @ Terminal input buffer address 
on TOS. 
LIT 0050 Limit length (80 bytes) 
EXPECT See above 
OIN ! Zero IN. 
*185 (See note) BLK @ Block number to TOS 
OBRANCH 
— 002A Go to 187 if TIB in use 
1 BLK +! Increment block number 
OIN! Zero IN 
BLK @ Block number to TOS 
B/SCR 1 — Blocks per screen — 1to TOS 
AND 0= Zero flag if (TOS AND 20S) = 0 
OBRANCH 
0008 if zero flag go to 186 
?7EXEC Error if not executing 
R> DROP Discard TORS 
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188 


189 


190 


191 
192 
193 


194 


195 


196 
197 


BRANCH 0006 End 
R>DROP Discard TORS 


The name field for this entry contains only CIH, 80H, indicating zero 
code. It switches blocks on a null code. 


FILL 


HL = BC. POP DE. POP BC. 
Exchange (SP),HL 
Exchange DE,HL 

If BC = Ogo to 190 

(DE) = L. INC DE. DEC BC. 
Go to 189 

POP BC. Go to NEXT1 


DE, then HL, hold the character to be used. The number of entries 
is held in BC, while HL, then DE, holds the start address, which is 
incremented after each entry. 


ERASE 
BLANKS 
HOLD 


PAD 


O FILL See above. 
BL FILL See above. 
LIT —1HLD +! Decrement HLD 


HLD @ C! Store TOS in (HLD) 
HERE 
LIT 0044 + TOS = HERE + 68 


The PAD buffer floats above the dictionary at a distance of 68 


bytes. 
WORD 


BLK @ TOS = block number 
OBRANCH 

O00C If TIB in use go to 196 
BLK @ TOS = block number 
BLOCK TOS = block address 


BRANCH 0006 Go to 197 


TIB @ TOS = TIB ADDRESS 

IN@ + Add IN 

SWAP Stack: addr delimiter 

ENCLOSE Stack: addr offset1 offset2 offset3 
HERE LIT 0022 

BLANKS Set up 34 space code entries. 

IN +! Add offset to IN 

OVER Stack: addr offset1 offset2 offset1 
— >R 

R HERE C! TORS = offset2 — offset1 


(HERE) = TORS 
+ HERE 1+ R>Stack: addr-+ offset1 
HERE+1 TORS 
Copy TORS bytes from 
address+offset1 to HERE+ 1 


CMOVE 
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198 (NUMBER) 


199 


200 


1+ DUP 
>R 
C@ 


BASE @ 
DIGIT 
OBRANCH 
002C 


Stack: X/Y addr+1 addr-+ 1 
TORS = addr+ 1 

TOS = (addr+ 1) 

(ASCIi numeric code) 

TOS = BASE 

Convert ASCI! code to number. 


lf invalid go to 200 


SWAP BASE @ Stack: X number Y BASE 
* 


Stack: X number Y*BASE 


DROP Discard upper word of double 
number product. 

ROT BASE 

@ U* Stack: number Y*BASE X*BASE 

D+ Stack: X*BASE + (Y*BASE + 
number) 

DPL @ 1+ TOS=DPL+1 

OBRANCH 

0008 lf DPL = —1 then go to 199 

1DPL +! Increment DPL (To count 
characters after point) 

R> Recover address from TORS. 

BRANCH FFC6 Go to 198 

R> Clear TORS 


This routine is normally called by NUMBER, which sets X/Y as 
zero. The process merits close scrutiny. 


201 NUMBER 


202 


00 ROT DUP 
1+ C@ 
LIT 002D 


DUP 
>R 
+ 


LIT -1 
DPL! 
(NUMBER) 
DUP C@ 


BL — 
OBRANCH 
0016 

DUP C@ 
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Stack: 0 0 addr addr 

Stack: 0 O addr (addr+ 1) 

Code for minus sign 

Zero flag if (addr+ 1) # minus 
sign code 

Duplicate flag 

Flag to TORS 

Stack: 0 0 addr-+ flag (Step past 
sign code) 


Set DPL 

See above 

Stack: number/number 
addr (addr) 

Compare with space code 


If space code go to 203 
Stack: number/number 
addr (addr) 


203 


LIT OO2E — Compare with decimal point code 


0 ?7ERROR Error if not decimal point 

0 Set DPL = 0 if decimal point. 
BRANCH FFDC Go to 202 

DROP R> Recover sign flag from TORS 
OBRANCH 

0004 If flag = O then end. 

DMINUS Negate result. 


NUMBER always produces a double number result. The upper 
byte its only discarded by INTERPRET if there is no decimal point. 


204 —FIND 


BL Space code to TOS 
WORD Copy name to HERE 
HERE Set up reference pointer 
CONTEXT @ @Set up search pointer 
(FIND) Search for word 

DUP Stack: PFA length flag flag. 
O= Reverse flag 

OBRANCH 

OOOA End if match found 

DROP Discard flag 

HERE Set up reference pointer 
LATEST Set search pointer to LATEST 
(FIND) Search again. 


If (FIND) fails, only the flag is left on the stack, so there is no need to 
discard the length byte and PFA. A search is then made starting at 
LATEST instead of (CONTEXT). 


205 (ABORT) 


206 ERROR 


207 


ABORT 
This word allows for special user versions of (ABORT) 

WARNING | 

@0< True flag if WARNING negative 

OBRANCH 

0004 lf WARNING not negative 
go to 207 

(ABORT) 

HERE 

COUNT TYPE Output offending word. 

(")%?” Output query, space. 

MESSAGE Output error number or text 

SP! Reset SP 

BLK @ —DUP Block number, duplicated if 
non-zero. 

OBRANCH 

0008 If TIB in use go to 208 


IN @ SWAP Stack: IN block 
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208 
209 _ ID. 


210 CREATE 


211 


*212 [COMPILE] 


QUIT 


PAD LIT 0020 
LIT OOSF FILL 


DUP PFALFA 
OVER — 

PAD SWAP 
CMOVE 


PAD COUNT 
LIT 001F AND 
2DUP 

+ 1— DUP 


@ 

LIT FF7F AND 
SWAP |! 
TYPE SPACE 


—FIND 


OBRANCH 
0010 
DROP 
NFA ID. 
LIT 0004 
MESSAGE 
SPACE 


Return to user control. 


Fill the PAD buffer with 

32 5F codes. 

Stack: NFA LFA 

Stack: NFA LFA—NFA 
Stack: NFA PAD LFA—NFA 
Copy LFA—NFA bytes from 
NFA to PAD 

Check copy length 

Limit to 31 bytes. 

Stack: addr length addr length 
Stack: addr length 
addr+length—1 

TOS = fast letter codes 
Remove bit 7 

Restore modified bytes 
Output word, add space. 


Search for word name 
and enter at HERE 


Go to 211 if unique 

Discard length 

Output word name 
Message 4 

Output number or message 
Add a space 


HERE DUP C@ Stack: HERE (HERE) 
WIDTH @ MIN $ Limit length to 31 characters 


1+ ALLOT 
DUP 

LIT OOAO 
TOGGLE 
HERE 1 — 
LIT 0080 
TOGGLE 
LATEST , 


CURRENT @! 


HERE 2+ , 
—FIND 


O= 


0 ?7ERROR 
DROP 
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Allot one more 
Stack: HERE HERE 


Toggle bits 5 and 7 of length byte 
HERE now modified by ALLOT 


Toggle bit 7 of last letter 

Set up link field 

CURRENT is read as an address. 
(CURRENT) = HERE 

Set up code field 


Search for word name and enter 
at HERE 

TOS = 0 if found. 

Error 0 if not found. 

Discard length byte 


*213 LITERAL 


"214 DLITERAL 


215 ?STACK 


216 INTERPRET 


217 
218 


219 


220 


CFA, 
STATE @ 
OBRANCH 
0008 


COMPILE LIT , 


STATE @ 
OBRANCH 
0008 
SWAP 
LITERAL 
LITERAL 
SP@ SO @ 
SWAP 

U< 

1 2ERROR 
SP@ HERE 
LIT OO80 + 
U< 


LIT 0007 
?7ERROR 


—FIND 


OBRANCH 
001E 
STATE @ < 


OBRANCH 
OO0A 
CFA, 


Set up code field 


lf executing then end. 
Set up LIT entry. 


lf executing then end. 


Stack: SP SO 

Stack: SO SP 

True flag if SP exceeds SO 
Error 1 if true flag 


Stack: SP HERE+ 128 
True flag if HERE + 128 is 
the greater 


Error 7 if true flag. 


Search for word name and 
enter it at HERE 


If not found go to 219. 
True flag if length ts 
less than state. 


lf faise go to 217 
Enter CFA at here 


BRANCH 0006 Goto 218 
CFA EXECUTE Execute indicated function. 


STACK Check stack bounds 

BRANCH 001C Go to 222 

HERE 

NUMBER Interpret word as number 

DPL @ 1+ TOS = DPL + 1 

OBRANCH 

0008 lf DPL = —1 goto 220 

DLITERAL Set up a double number 

BRANCH 0006 Go to 221 

DROP Discard upper byte of 
double number. 

LITERAL Set up a single number. 
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221 
222 


word first. 
223 IMMEDIATE 


?STACK 


Check stack bounds 


BRANCH FFC2 Go to 216 


The comparison of the length byte with state implements the 
special characteristics of some words. Note that if a word name 
happens also to be a valid number in the current BASE, it will not be 
possible to input that number, as it will always be interpreted as a 


LATEST 
LIT 0040 


TOGGLE 


224 VOCABULARY <BUILDS 


225 
*226 FORTH 


227 (space) 
228 DEFINITIONS 


*299 | 
230 QUIT 


231 


232 
233 ABORT 


LIT A081 , 
CURRENT @ 
CFA, 


HERE 


VOC—LINK @ , 


VOC—LINK ! 


DOES> 
2+ CONTEXT ! 


CONTEXT @ 
CURRENT ! 


LIT 0029 
WORD 


OBLK! 


RP! 

CR QUERY 
INTERPRET 
STATE @ 0= 
OBRANCH 
0007 

“OK” 
BRANCH FFE7 
SP! 
DECIMAL 
?STACK 
CLS CR 
.CPU 
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Toggle bit 6 of LATEST 


Set up a constant entry. 
Store A081 at HERE 


Store CFA of CURRENT 
at HERE 


Store VOC—LINK at HERE 
Store previous HERE at 
VOC—LINK 


Set CONTEXT toCURRENT + 2 


Execute code at 164 
Execute 225 


Zero code field. 


CURRENT = CONTEXT 
Delimiter is close bracket. 
Set up comment but ignore. 
Set block = 0 (TIB in use) 
STATE =0 

Initialise RSP 

Newline. Get input text 
Interpret text 

True flag if executing. 


If false flag go to 232 

Output “ok” 

Go to 231 

Initialise SP 

Select decimal representation. 
Check stack bounds 

Clear screen, newline 

Output “48K Spectrum” 


234 Entry from 


235 
236 WARM 


237 Entry from 


238 
239 COLD 


240 S->D 


241 +— 


(.’’) text 
CR 
(.”) text 
CR 


FORTH 
DEFINITIONS 
QUIT 


WARM start 


EMPTY- 
BUFFERS 
ABORT 


COLD start 


EMPTY- 
BUFFERS 


Output “fig-FORTH 1.1A” 
Newline 

Output ’(C) Abersoft: 1983 
Newline 

Select FORTH vocabulary 
CURRENT = CONTEXT 
Return control to user. 


BC = address of link to 236 
IX = (5E66) = 5E00 

HL = (5E52) = CB40 

SP = HL 

Go to NEXT1 (Thence to 236) 
Link to CFA for WARM 


Mark buffers as empty 
See above. 


(FLAGS2) = 8 (BASIC variable) 
(hold) = 0 (See 266) 

BC = address of link to 267 

IX = (5E66) = 5E00 

HL = (5E52) = CB40 

SP = HL 

Go to NEXT1 

Link to CFA for COLD 


Mark buffers as empty 


LIT CBEO USE ! Set next buffer = CBEO 


LIT CBEO 
PREV ! 
DRO 

LIT 5E52 
LIT 5E66 @ 
LIT 0006 + 
LIT 0010 
CMOVE 


LIT 5E4C @ 
LIT 6CF8 ! 
ABORT 


O< 
OBRANCH 
0004 
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Set last buffer = CBEO 
OFFSET = 0 


Stack: 5E52 (5E66)+6 16 

Copy 16 bytes, starting with 
5E52 to 5E06 

TOS = 8149 

(G6CF8) = 8149 (Link field of 227) 


POP DE. HL = 0.A = DAND 80H 
lf A #0 then DEC HL. 
Go to PUSHDE 


If TOS negative true flag 


lf false flag then end 


242 


243 
244 


245 


246 
247 


248 


249 


250 


251 
252 


253 


D+— 


ABS 
DABS 


MIN 


MAX 


Mi* 


M/ 


* 


/MOD 


/ 


MINUS 
O< 
OBRANCH 
0004 
DMINUS 
DUP +— 
DUP D+ — 


2DUP > 


OBRANCH 
0004 
SWAP 


DROP 
2DUP < 


OBRANCH 
0004 
SWAP 


DROP 
2DUP XOR > R 


ABS SWAP 
ABS 

Us 
R>D+-—- 


OVER >R>R 
DABS 


R ABS 
U/MOD 
R>RXOR 


-4- —_— 
SWAP 
R> +-— 
SWAP 
M* DROP 


>R S->D R> 


M/ 


/MOD SWAP 
DROP 
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Negate TOS 
True flag if TOS negative 


if false flag then end. 
Negate double word. 
if TOS negative then negate 


If TOS negative then negate 
double word. 


If 20S greater than TOS then 
true flag. 


If false flag go to 246 


Discard the greater. 


If 20S less than TOS then 
true flag. 


If false flag to to 248 


Discard the lesser. 


TORS = TOS XOR 20S 
(Stack preserved) 


Make TOS,20S positive 
Product of TOS*20S 
Negate result if signs of 
TOS,20S differed. 
Stack: X Y TORS = Z 2ORS = Y 
Convert double number 

to positive 

Convert Z to positive 

Stack: rem quot. 

Negative if signs of XY and 

2 differ 

lf negative then negate quotient. 


Negate remainder if Z negative 
Discard upper half of product 
Sign extend 20S 

As above. 


Discard remainder 


294 
255 


256 


20/ 


258 


299 


260 


261 
262 


263 


264 


MOD 
*/MOD 


*/ 


M/MOD 


(LINE) 


.LINE 


MESSAGE 


/MOD DROP _ Discard quotient 


>R TOS to TORS 
M* Product 
R> Restore original TOS 
M/ Remainder Quotient 
*/MOD SWAP 
DROP Discard remainder 
>ROR Make 2OS double 
U/MOD Remainder quotient1 
R> SWAP >R_ Remainder divisor 
TORS hold quotient1 
U/MOD R> Remainder quotient2 quotient1 
>R Stack: Line TORS: Screen 
LIT 0040 
B/BUF Bytes per buffer 
*/MOD Line*64/bytes per buffer. 
(Rem and quot) 
R>B/SCR* Rem quot Screen*B/SCR 
+ Rem quot+ Screen*B/SCR 
BLOCK + Add block address 
LIT 0040 
(LINE) see above 
—TRAILING _ Discard trailing spaces 
TYPE Output 
WARNING @ 
OBRANCH 001E If WARNING = 0 go to 262 
—DUP Duplicate if non-zero 
OBRANCH 0014 If message 0 then go to 261 
LIT 0004 Screen 4 
OFFSET @ Block offset 
B/SCR / Divide by blocks per screen 
— Subtract from screen number 
LINE Output message 
SPACE Add a space 
BRANCH O000D End 
( ”) text Output “MSG # ” 
Output number. 


The following code is used by ?TERMINAL (see 34) BASIC 
routines are involved. 


PUSH BC. PUSH DE. CALL 
1F54. HL = 0 

If carry go to 264. 

Else INC L.. Go to 265 


lf (5CO8) = 7 then INC HL. 
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265 


266 


267 
268 


269 


270 
271 


2/2 


273 


2/74 


POP DE. POP BC. Go to 
PUSHHL. 


The following code is used by KEY. (See 33) BASIC routines are 


involved. 


PUSH BC, A=2. CALL 1601. 
A=12. RST10A = 1. RST10. 
(5CO8) = 0 

A = (hold). RST10. A=8. RST10 - 
If (5CO8) = O then go to 268 

lf (5CO8) 4 6 then go to 271 

HL = 5C6A. (HL) = (HL) XOR 8 
HL = hold. If bit3 of A = 1 then go 
to 270 

(HL) = 4CH. Go to 267 

(HL) = 43H. Go to 267 

lf A #OFH then go to 273 

A = 2. HL = 5C41. 

(HL) = (HL) XORA 

If (HL) = 0 then go to 272 

A = (5C6A). Go to 269 

A = 47H. (hold) = A. Go to 267 


In BASIC, 5C08 is LASTK 5C41 is MODE. 5C6A is FLAGS2 
The routine from 273 onwards is mainly concerned with recoding 


certain keys. 


C6 (AND) becomes 5B Si 

C5 (OR) becomes 5D _ ssi 

E2 (STOP) becomes 7E ~ 

C3 (NOT) becomes 7C_ | 

CD (STEP) becomes 5C / 

CC (TO) becomes 7B { 
CB(THEN)becomes7D } 

lf A is greater than A5H (after the 
above conversions) go to 267 
(i.e. ignore input) Else L = A. 

H = 0. A = 12. RST10. A = 0 
RST10. A = 20. RST10. A = 8. 
RST10. POP BC Go to PUSHHL. 


The following code is used by EMIT (See 32). Once again, BASIC 


routines are involved. 
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PUSH BC. PUSH HL. A = 2. 
CALL 1601 POP HL. PUSH HL. 
A = 1.RST10. A = (hold2). 

If A =O goto 275 


275 


276 


277 


278 
279 
280 
281 


282 


283 


284 


285 


286 
287 
288 


CALL 1601. POP HL. PUSH HL. 
A=L.RST10 
POP HL. A = FFH. (5C8C) = A. 
POP BC. Go to NEXT 1 
5C8C in BASIC is SCRCT (Scroll count). Setting it to FFH ensures 
permanent scrolling. The contents of hold2 control the printer (see 
337). 
The following code is used by CR (See 35). 
PUSH BC. A=2. CALL 1601. A = 
2DH. RST 10 
A = (hold2). If A= 0 
then go to 277. 
CALL 1601. A = OD. RST10. 
POP BC. (5C8C) = FFH. 


Go to NEXT 1. 
USE TOS = (Oldest block buffer) 
PREV TOS = (Last block buffer) 
#BUFF TOS = (Number of disc buffers) 
+BUF LIT 0084 + Stack: Addr+ 132 


DUP LIMIT = Stack: Addr-+ 132 true flag if 
Addr+ 132 = LIMIT 

OBRANCH 0006 If false flag go to 282 

DROP FIRST Substitute FIRST 


DUP PREV @ — Compare with PREV. 


(Leave addr flag) 
UPDATE PREV @ @ TOS = contents of PREV 
LIT 8000 OR 
PREV @! Set bit 15 of contents of PREV. 
EMPTY-BUFFERS 
FIRST LIMIT 
OVER — Stack: FIRST LIMIT-FIRST 
ERASE Clear buffer area to zero. 
LIMIT FIRST 
(DO) From First to LIMIT — 1; 
LIT 7FFF I! Set 7FFF at (i) 
LIT 0084 Step 132 
(+LOOP) FFF2 Loop to 285 
DRO OOFFSET ! SetOFFSET toO 
BUFFER USE @ DUP >RStack: (USE) TORS: (USE) 
+BUF Advance to next buffer. 
OBRANCH FFFCIf PREV go to 288 


USE |! Mark as in use 
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289 


290 BLOCK 


291 


292 


293 


294 LO 
295 Hi 
296 R/W 


R@0< If last buffer updated (negative) 
set true flag. 
OBRANCH 0014 If false flag go to 289. 
R2+ R@ (USE) = (USE) + 2. ((USE)) 
LIT 7FFF AND Zeromsb 


0 R/W Writer buffer to disc. 

R! Set (USE) as written 

R PREV! Set PREV = USE 

R> 2+ Leave (USE) + 2 

OFFSET @+ Stack: blockno + offset 

>R Transfer to TORS 

PREV @DUP Stack: PREV PREV 

@ Stack: PREV (PREV) 

R — DUP STACK: PREV (PREV)—TORS 

+ Stack: PREV+(PREV)—TORS 

OBRANCH 0034If zero go to 293 

+BUF 0= Move to next buffer. True if PREV 

OBRANCH 0014 Go to 292 if false. 

DROP Discard buffer address 

R BUFFER See above (Blockno-+ offset 
provides data) 

DUP Duplicate address 

R1R/W Read into last buffer 

2— Modify address 

DUP @R —- Compare buffer data with TORS 

DUP + Double TOS 

0O= Reverse flag state 


OBRANCH FFD6If false flag go to 291 
DUP PREV! SetPREV 


R> DROP Discard TORS 
2+ Advance address 


TOS = D000 (Start of RAM-disc) 
TOS = FBFF (End of RAM-disc) 


>R TORS = direction flag 
(O=write, 1=read) 

B/BUF * Stack: addr block* 128 

LO + Stack: addr block* 128 + DOOO 

DUP HI > True flag if limit exceeded 

LIT 0006 Error 6 

?7ERROR Report error if true flag 

R> Clear TORS. Direction flag 
on TOS 


OBRANCH 0004 Go to 297 if false 
SWAP 
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297 


298 FLUSH 


299 


300 LOAD 


*301 --> 


*302 (tick) 


303 BACK 
*304 BEGIN 


*305 ENDIF 


*306 THEN 
*307 DO 


308 LOOP 


B/BUF 
CMOVE Copy a buffer-full as instructed. 
#BUFF 
1+ 
0 (DO) 
BUFFER DROP 
(LOOP) FFF8) Loop to 299 
DUP 0 = True flag if match 
LIT 0009 Error number 9 
?ERROR Report error if true 
(load from screen 0) 
BLK @ Read block number 
>R Block no to TORS 
IN@>R IN to TORS 
OIN! IN=0 
B/SCR * Screen*B/SCR 
BLK ! Write to BLK 
INTERPRET 
R> IN! Restore IN 
R> BLK! Restore BLK 
?LOADING Error tf not loading 
OIN! IN=0 
B/SCR BLK @ B/SCR BLK 
OVER B/SCR BLK B/SCR 
MOD BLK rem of BLK/B/SCR 
— BLK +! BLK = BLK + BLK — rem 
—FIND O— Search for name. Reverse flag 
0 ?7ERROR Error 0 if not found. 
DROP Discard length byte 
LITERAL 
HERE — , Store addr - HERE 
?COMP Error if not compiling 
HERE 1 Identifies loop point. 
Sets PAIRS ref = 1 
?COMP Error if not compiling 
2 ?PAIRS Error if PAIRS ref not 2 
HERE OVER - Stack: aHERE-a 
SWAP ! Write link span. 
ENDIF The words mean the same. 
COMPILE (DO) 
HERE 3 Identify loop point. 
PAIRS ref = 3 
3 ?PAIRS Error if PAIRS ref not 3 


COMPILE (LOOP) 
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*309 +LOOP 
*310 UNTIL 


*311 END 
*312 AGAIN 


“313 REPEAT 


*314 IF 


*315 ELSE 


*316 WHILE 


317 SPACES 


318 


319 <# 
320 #> 


321 SIGN 


BACK Caiculate backward link span. 


3 ?PAIRS Error if PAIRS ref not 3 

COMPILE (+LOOP) 

BACK Calculate backward link span. 

1 ?PAIRS Error if PAIRS ref not 1 

COMPILE OBRANCH 

BACK Calculate backward link span 

UNTIL The words mean the same 

1 ?7PAIRS Frror if PAIRS ref not 1 

COMPILE BRANCH 

BACK Calculate backward link span. 

>R>R TOS, 2OS to return stack 

AGAIN 

R> R> TOS,2OS restored 

2—- Convert PAIRS ref from 4 to 2. 
(See WHILE) 

ENDIF 

COMPILE OBRANCH 

HERE 

0, Reserve space 

2 PAIRS ref = 2 

2 ?PAIRS Error if PAIRS ref not 2. 

COMPILE BRANCH 

HERE 

O, 

SWAP 

2 ENDIF 2 PAIRS ref = 2 

IF 2+ Execute IF, then increase PAIRS 
ref by 2. 

0 MAX Ensure positive value 

—DUP Duplicate if non-zero 

OBRANCH 000C End if TOS = 0 

0 (DO) 

SPACE Output space. 

(LOOP) FFFC Loop to 318 

PAD HLD ! Set HLD = PAD 

DROP DROP _ Discard balance of number 

HLD @ Read HLD 

PAD OVER -—_ Stack: HLD PAD-HLD 

ROT Bring sign to TOS 

O0< True if TOS less than 0 


OBRANCH 0008 If TOS = 0 then end. 
LIT O02D Minus sign code 
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322 


323 


324 


325 


326 


327 


328 . 


329 


330 


331 


332 


HOLD Store at HLD 


# BASE @ Stack: XY BASE 
M/MOD Stack: rem double-quotient 
ROT Stack: double-quotient rem. 
{1 0009 OVER Stack: double-quotient rem 
9 rem. 


TOS true if rem exceeds 9 
OBRANCH 0008 Go to 323 if false. 
LIT 0007 + Add 7 to rem 


LIT 0030 + Add 48 to form ASCII code 


HOLD Store at HLD 
#S # See above 
OVER OVER _ Stack: double-number 
double-number 
OR 0= True flag if number = 0 
OBRANCH FFF4 If false go to 324 
D.R >R SWAP OVERStack: Y X Y (XY double number) 
TORS =n 
DABS Make XY positive 
<# #98 Set up number in PAD 


SIGN #> Add sign 
R>OVER-— — Stack: addr count n-count 
SPACES Output n-count spaces 
TYPE Output number 
Note that the number is reduced to zero by #S, so the sign has to be 
determined from the copy of Y. 


.R >R nto TORS 
S—->D Sign extend to double number. 
R> Restore n 
D.R Above 

D. 0 Call for a zero-length field. 
D.R See above 
SPACE Add a space 
S-—-—>D Sign extend to double number 
D. See above 

? @. Print contents of address 

specified on TOS 

U. 0 Form double number, unsigned 
D. see above 

VLIST LIT 0080 
OUT! OUT = 128 
CONTEXT @ @Contents of CONTEXT on TOS 
OUT @ 


LIT OO1F 
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333 


334 


335 


336 


337 


338 


339 


340 


LIT 0008 Stack: (CONTEXT) OUT 318 
-> True flag if OUT exceeds 23 
OBRANCH OO0A If false flag go to 333 
CROOUT! Newline. OUT = 0 


DUP Duplicate pointer 

ID. Output name 

PFA LFA @ Read link field 

DUP O= True flag if zero 

?7TERMINAL _ True flag if BREAK 

OR Either true flag effective 

OBRANCH FFDOIf false flag loop to 332 

DROP Drop last address 
LIST DECIMAL 

CR Newline 

DUP SCR! set chosen screen 

(.”’) text Output’SCR #’ 

. Output screen number 

LIT 0010 

0 (DO) 

CR Newline 

| Line number 

LIT 0003 .R Print in a three-space field 

SPACE Add a space 

|SCR @ 

LINE Output stored line 


?TERMINAL ~~ True if BREAK 
OBRANCH 0004 If false go to 336 


LEAVE 
(LOOP) FFE2 Goto335 
CR Newline 
LINK POP HL.A=L. IfA#O0thenA=3 
(hold2) = A. Go to NEXT 1 
CLS PUSH BC. A=2. CALL 1601. 


CALL OD6B A=2. CALL 1601. 
POP BC. Go to NEXT1 


CPU (.’’) text Output “48K SPECTRUM ” 
At this point, an area is reserved for tape headers of the form: 
03 44 49 53 43 20 20 20 20 20 20 FF 2B 00 DO 20 20 
DISC 
03 44 49 53 43 20 20 20 20 20 20 FF 2B 00 DO 20 20 
DISC 
(TAPE) POP HL. PUSH BC. PUSH IX. 
A =L. HL = DOOO. IX = (start of 
header area). A = (5C72). 
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341 


342 


343 


344 
345 
346 
347 
348 


349 


350 
351 


MON 


TEXT 


LINE 


LOADT 
SAVET 
VERIFY 
2DROP 
2SWAP 


SIZE 


FREE 
FORGET 


HERE 
C/L1+ 
BLANKS 
WORD 


HERE PAD C/L 


1+ CMOVE 
DUP 

LIT FFFO AND 
LIT 0017 
?ERROR 
SCR @ 
(LINE) 

DROP 


1 (TAPE) 


FLUSH 0 (TAPE) 


2 (TAPE) 
DROP DROP 
ROT >R 


ROT R> 


HERE 
O +ORIGIN — 


SP@ HERE — 
CURRENT @ 


CONTEXT @ — 


LIT 0018 
?ERROR 


DUP 

FENCE @ U< 
LIT 0015 
?7ERROR 
DUP NFA 


DUP ! 
LFA @ 


CALL 075A. POP IX. POP BC. 
Go to NEXT 1 


A = (5CBO). If A = 0 then RSTO8 
Else go to NEXT1 


Stack: HERE C/L+ 1 
Set up a line of spaces at HERE 
Set string at HERE 


Copy complete line to PAD 
Stack: Line Line 

Limit to 15 

Error number 23 

Error if non-zero 

Read current screen 

Set up line address and account 
Drop length count. 


Stack fomabcdtoacd 
bon TORS 
Stack:cdab 


TOS = HERE — ORIGIN 
TOS = SP — HERE 


TOS = CURRENT — CONTEXT 
Error number 24 

Report error if non-zero 

TOS = PFA of word to be 
forgotten. 

Duplicate 

True flag if PFA below FENCE 
Error number 21 

Error if TOS true. 

Duplicate PFA and substitute 
NFA for copy. 

DP = NFA 

Convert PFA to LFA and read link. 


CURRENT @ ! Setlink at location defined 
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by CURRENT. 


Note that no actual! erasure occurs. Because the pointers have 
been reset, new entries will over-write the debris. 


352 INDEX 


353 


354 
355 TRIAD 


356 


357 
“358 EDITOR 


359 (space) 


360 WHERE 


CLS 
1+ SWAP 


(DO} 
CR 
13 .R 


SPACE 
O!.LINE 
? TERMINAL 


Clear screen 
Reverse parameters, 
incrementing end. 


Newline 

Output screen number in a 
three-space field. 

Add a space 

Output line 0 of screen | 
Set true if BREAK 


OBRANCH 0004 Go to 354 if no BREAK. 


LEAVE 
(LOOP) FFE6 


CLS 

3 / 

3 * 

3 OVER + 
SWAP 

(DO) 

CR 

LIST 
?7TERMINAL 


Terminate loop 
Loop to 353 


Clear screen 

Divide screen number by 3. 
Multiply by 3. (Result x) 
Stack: X X+3 

Stack: X+3 X 


Newline 
list screen | 
TOS = 1 if BREAK 


OBRANCH 0004 If no BREAK go to 357 


LEAVE 
(LOOP) FFFO 


DUP 
B/SCR / 
DUP SCR! 


(.”’) text 
DECIMAL . 
SWAP C/L 
/MOD 
C/L* 

ROT 
BLOCK + 
CR 

C/L TYPE 
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Terminate loop 
Loop to 356. 


Execute code at 164 
Execute 225 


Links to last item in EDITOR 
vocabulary. Calls 227 


Stack: IN BLK BLK 
Stack: IN BLK BLK+B/SCR 
Set SCR from TOS. 
Stack unchanged. 
Output “SCR # ” 
Output screen number. 
Stack: BLK IN C/L 
Stack: BLK rem quotient 
Stack: BLK rem line 
Stack: rem line BLK 
Stack: rem line+ addr 
Newline 

Type line. 


361 


362 


363 


364 


365 


366 


367 


368 


CR 

HERE C@ 
SPACES 
LIT OO5E 
EMIT 
EDITOR 
QUIT 


Ls eae dl 


Newline (Stack: rem) 
Stack: rem — (HERE) 
Output TOS spaces 

Code for upward arrow 
Output character 

Select EDITOR vocabulary 
Return control to user. 


This very useful routine may be called following an error to find the 
location of the error. It sets EDITOR mode and clears the stacks. 
This is the start of the EDITOR vocabulary. This item links on to 
the start of the FORTH vocabulary via entry 227. in VLIST, with the 
EDITOR selected, the EDITOR vocabulary appears first, followed 
by the FORTH vocabulary. 


#LOCATE 


#LEAD 


#LAG 


—MOVE 


R# @ 

C/L /MOD 
#LOCATE 
LINE 
SWAP 


#LEAD 
DUP 
>R 

+ 

C/L R> 


LINE 


C/L 
CMOVE 
UPDATE 


LINE PAD 1 + 


C/L DUP 
PAD C! 
CMOVE 


LINE C/L 
BLANKS 
UPDATE 
DUP 1 — 
LiT OOOE 
(DO) 

| LINE 
l1+ 
—MOVE 
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Read cursor location 
Stack: column line 


See above 
Stack: column addr 
Stack: addr column 


See above 

Stack: addr column column 

TOS to TORS 

Stack: addr+column 

Stack: addr+column C/L column 
Stack: addr+column 
C/L—column 

Stack: addr1 addr2 

(TOS = address of line) 

Stack: addr1 addr2 C/L 

Copy one line from addr1 to addr2 


Stack: Line-addr PAD+ 1 

Stack: Line-addr PAD+ 1 C/L C/L 
Stack: 1st PAD location set to C/L 
Copy one line from Line-addr 

to PAD. 

Stack: addr C/L 

Fill line with spaces 


Stack: Line Line—1 
Address of line | 


+1 
Copy line | to line I+ 1 
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370 


371 


372 


373 


374 


375 


376 


LIT —1 


LOOP) FFFO Go to 368 
Erase line 
D DUP Stack: Line Line 
H Copy line to PAD 
LIT OOOF 
DUP ROT Stack: 15 15 Line 
(DO) 
11+ LINE Address of line |+ 1 
| 
—MOVE Copy line I+ 1 to line | 
(LOOP) FFF4 Goto370 
E Erase line 15. 
M R# +! Add TOS to cursor position. 
CR SPACE Newline, space 
#LEAD TYPE Output text to cursor 
LIT OO5F Code for underline 
EMIT output code 
#LAG TYPE Output text from cursor to 
end of line. 
#LOCATE . Output line number 
DROP Discard column. 
T DUP Stack: Line Line 
C/L* Stack: Line Line*C/L 
R# ! Set cursor position to line start. 
DUP Stack = Line Line 
H Copy line to PAD - 
OM Output line. (cursor at left end) 
L SCR @ Read current screen number 
LIST List that screen 
OM Display cursor line. 
R PAD 1+ SWAP Stack: PAD+ Line 
—MOVE Copy line from PAD to 
specified line. 
Pp 1 TEXT Set text in PAD. (Delimiter is 1) 
R Copy text to specified line. 
| DUP Stack: Line Line 
S Spread at Line 
R Copy line from PAD 


Note that R and | are not unique. While the EDITOR is effective, the 
FORTH meanings are replaced. However, the original R is used by 


several EDITOR definitions. 
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377 TOP 
378 CLEAR 


379 


380 COPY 


381 


382 —TEXT 


383 


384 
385 


386 
387 MATCH 


OR#! Set cursor position to zero. 

SCR |! Set screen from TOS 

LIT 0010 0 Sixteen iterations 

(DO) 

IE Erase line | 

(LOOP) FFFA Goto379 

B/SCR * Stack: SCR1SCR1*B/SCR 

OFFSET @+ Add OFFSET 

SWAP Stack: SCR2*B/SCR+ OFFSET 
SCR1 

B/SCR * Stack: SCR2*B/SCR+OFFSET 


SCR1*B/SCR (= AB) 
B/SCR OVER + Stack: ABB+B/SCR 


SWAP Stack: AB+B/SCRB 

(DO) 

DUP Stack: AA 

1 BLOCK Address of block | 

2! Write A to address—2 

1+ Stack: A+ 1 

UPDATE 

(LOOP) FFEE Loop to 381 

DROP Discard A 

FLUSH Copy updated buffers to 
RAM-disc. 

SWAP Stack: Addr1 Addr2 Count 

—DUP Duplicate TOS if non-zero 

OBRANCH 002A If zero go to 386 

OVER + Stack: Addr1 Addr2 
Addr2+Count 

SWAP Stack: Addr1 Addr2+ Count 
Addr2 

(DO) 

DUP Stack: Addr Addr 


C@!IC@ - Stack: Addr (Addr) — (I) 
OBRANCH OOO0A If zero go to 384 


O= True flag if zero 
LEAVE 

BRANCH 0004 Go to 385 

1+ Increment address 


(LOOP) FFE6 Loop to 383 
BRANCH 0006 End 


DROP 0= Discard address. Set false flag. 
>R>R Stack: Addr1 Count. 
(Addr2 Count2 on RS) 
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388 


389 


390 1LINE 


391 FIND 


392 


394 DELETE 


2DUP 


R> R> Stack: Addr1 Count1 Addr1 
Count1 Addr2 Count2 

2SWAP Stack: Addr1 Count1 Addr2 
Count2 Addr1 Count1 

OVER + Stack: Ad1 Ct1 Ad2 Ct2 Ad1 
Ad1+Ctt 

SWAP Stack: Ad1 Ct1 Ad2 Ct2 
Ad1+Ct1 Ad1 

(DO) 

2DUP Stack: Ad1 Ct1 Ad2 Ct2 Ad2 Ct2 

| —TEXT Stack: Ad1 Ct1 Ad2 Ct2 flag 


OBRANCH 001A If false go to 389 
>R 2DROP R> Discard 20S,30S 


— | SWAP — 

O SWAP 00 

LEAVE Terminate loop 

(LOOP) FFDC_ Loop to 388 

2 DROP SWAP 

O= Reverse flag 

SWAP 

#LAG PAD Stack: cursor toEOL PAD 

COUNT Stack: cursor toEOL PAD count 

MATCH 

R# +! Update cursor position. 

LIT OSFF 

R# @< True if cursor position less than 
O3FF 

OBRANCH 0012 If zero go to 392 

TOP Zero cursor position. 

PAD HERE 

C/L 1+ 

CMOVE Copy from PAD to HERE, 
C/L+1 bytes 

O ERROR Report error 0 

TLINE See above 

OBRANCH FFDE If zero go to 391 

>R #LAG Stack: Cursor toEOL n to TORS. 

+R- Stack: Cursor toEOL—n 

#LAG Stack: Cursor toEOL—n 
Cursor toEOL 

R MINUS Add to stack —n 

R# +! Add —n to cursor position 

#LEAD + 

SWAP 
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395 


396 


398 


399 


400 


401 


402 


CMOVE 


R> BLANKS 
UPDATE 
N FIND Search 
OM Display 
F 1 TEXT Text to PAD 
N Find next 
B PAD C@ Read length from PAD 
MINUS Negate 
M Add to cursor position. 
4 1 TEXT Text to PAD 
FIND Locate 
PAD C@ Read length from PAD 
DELETE Delete last n characters 
OM Display line 
TILL #LEAD + Line+column 
1 TEXT Text to PAD 
1LINE 
O= Reverse flag 
0 ?7ERROR Error if true 
#LEAD + Line+column 
SWAP — 
DELETE 
OM Display line 
C 1 TEXT Text to PAD 
PAD COUNT Modify references 
#LAG 
ROT OVER Stackabctobcac 
MIN >R 
RR# +! Add TORS to cursor position. 
R-—>R 
DUP HERE R 
CMOVE 
HERE #LEAD 
+ R> 
CMOVE 
R> 
CMOVE 
UPDATE 
OM Display line 


This completes the EDITOR vocabulary. When the vocabulary is 
enabled, dictionary searches start with the C entry. The NEXT entry 
below links on to WHERE (360) 


NEXT 


Constant returning address of 
link 3 
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403 


404 


405 


406 


407 


408 


409 


410 


411 


412 


413 


414 


INP 


OUTP 


SCREEN 


AT 


BORDER 


BLEEP 


PAPER 


PUSHHL Constant returning address of 


link 2 


Constant returning address of 
link 1 


POP HL. PUSH BC. BC=HL IN 
A, (C). POP BCH =0.L=A. 
PUSH HL. Go to NEXT1 

POP HL. POP DE. PUSH BC. 
BC = HLA = E. OUT (C),A. 
POP BC. Go to NEXT1 

POP HL. POP DE. PUSH BC. 
PUSH IX. C = E.B =L. 

CALL 2538. CALL 2BF1. A = 
(DE). H = 0.L =A. POP IX. 
POP BC. PUSH HL. Go to NEXT1. 


Stack: line col col 


PUSHDE 


ABS DUP 
LIT OO1F > 
OBRANCH 0008 if col not greater than 31 go to 409 
2DROP Clear stack 

BRANCH 0022 End. 


SWAP ABS DUPStack: col line line 


LIT 0015 > 

OBRANCH 0008 If line not greater than 21 
go to 410 

2DROP Clear stack 

BRANCH 000C End 

LIT 0016 

EMIT Output 22 

EMIT Output line 

EMIT Output col 
POP HL. PUSH BC. A = L. 
CALL 2297. POP BC. 
Go to NEXT1 
POP HL. POP DE. PUSH BC. 
PUSH IX. CALL 03B5. POP IX. 
POP BC. Go to NEXT1. 

ABS DUP 

LIT 0009 > 

OBRANCH 0008 If parameter not greater than 9 
go to 414 

DROP Clear stack 

BRANCH 0088 End 

DUP 

LIT 0009 = 
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415 


416 


417 ATTR 


418 POINT 


419 INK 


OBRANCH 001A If parameter not 9 then go to 415 
LIT 5C91 Address of PFLAG 

C@ Read PFLAG 

LITOO8O0OR = Set bit3 

LIT 5C91 C! Write to PFLAG 


DROP Discard parameter. 

BRANCH 0064 End 

DUP 

LIT 0008 = 

OBRANCH 001A If parameter not 8 then go to 416 
LIT 5C8E Address of MASKP 

C@ Read MASKP 

LITQO38OR = Set bits 3, 4, 5 

LIT 5C8E Address of MASKP 

DROP Discard parameter. 


BRANCH 0040 End 

LIT 0008 * Multiply parameter by 8 

LIT5C8D C@ Read ATTRP 

LITOOC7 AND Zero bits 3, 4,5 

OR OR parameter 

LIT5C8DC! #£WritetoATTRP 

LIT5C91C@ Read PFLAG 

LITOO7F AND Zero bit 7 

LIT 5C91! Write to PFLAG 

LIT 5C8EC@ Read MASKP 

LITOOC7 AND Zero bits 3, 4,5 

LIT 5C8E ! Write to MASKP 
POP HL. POP DE. PUSH BC. 
PUSH IX.C = E.B=L. 
CALL 2583. CALL 1E94. H = 0. 
1 = A. POP IX. POP BC. 
PUSH HL. Go to NEXT1 
POP HL. POP DE. PUSH BC. 
PUSH IX.C = E.B=L.A=L. 
lf Ais not less than HOH then 
A = AFH, B = A. CALL 22CE. 
CALL 1E94.H =0.L=<A. 
POP IX. POP BC. PUSH HL. 


Go to NEXT 1. 

ABS DUP 

LIT 0009 > 

OBRANCH 0008 If parameter not greater than 9 
go to 420 

DROP Discard parameter. 


BRANCH 0082 End 
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420 


421 


422 


423 


424 


425 


426 


FLASH 


BRIGHT 


DUP 

LIT 0009 = 

OBRANCH 001A If parameter not 9 then 
go to 421. 

LIT5C91C@ ReadPFLAG 

LITOO20OR_ = Set bit 5 

LIT 5C91 C! Write to PFLAG 

DROP Discard parameter 

BRANCH 005E End 


DUP 

LIT 0008 = 

OBRANCH 001A If parameter not 8 then 
go to 422 

LIT5C8EC@ Read MASKP 

LITO0007OR ~~ Setbits 0, 1, 2. 

LIT5C8EC! Write to MASKP 

DROP Discard parameter 

BRANCH 003A End 


LIT5C8D C@ Read ATTRP 

LITOOF8 AND Zero bits 0, 1, 2. 

OR OR parameter. 

LIT5C8DC! #£WritetoATTRP 
LIT5C91C@ Read PFLAG 

LITOODF AND Zero bit 5 

LIT 5C91 ! Write to PFLAG (Word write) 
LIT 5C8EC@ Read MASKP 

LITOOF8 AND Zero bits 0, 1, 2. 

LIT 5C8E ! Write to MASKP (Word write) 
OBRANCH 0018 If parameter 0 then go to 424 
LIT5C8DC@ Read ATTRP 

LITOO80OR Set bit 7 

LIT 5C8D ! Write to ATTRP (Word write) 
BRANCH 0014 End 


LIT5C8DC@ Read ATIRP 
LITOO7F AND Zero bit 7 
LIT 5C8D |! Write to ATTRP (Word write) 


OBRANCH 0018 If parameter 0 then go to 426 
LIT5C8DC@ Read ATTRP 

LITOO40OR_ Set bit 6 

LIT 5C8D |! Write to ATTRP (Word write) 
BRANCH 0014 End 


LIT5C8DC@ Read ATTRP 
LITOOBF AND Zerobit6 
LIT 5C8D! Write to ATTRP (Word write) 
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427 GOVER OBRANCH 0016 If parameter 0 go to 428 
LIT5C91C@ Read PFLAG 
20OR Set bit 1 
LIT 5C91 ! Write to PFLAG 
BRANCH 9914 End 
428 LIT5C91C@ Read PFLAG 
LITOOFD AND Zero bit 1 
LIT 5C91 ! Write to PFLAG (Word write) 
429 INVERSE OBRANCH 0018 If parameter 0 go to 430 
LIT5C91C@ ReadPFLAG 
LITOOO8OR ss Sett bit3 


LIT 5C91 ! Write to PFLAG 

BRANCH 0014 End 
430 LIT5C91C@ Read PFLAG 

LITOOF7 AND Zerobit3 

LIT 5C91! Write to PFLAG (Word write) 
431 NOT O= Synonyms. 
432 I HL = (RSP) + 2. DE = (HL). 

PUSH DE. Go to NEXT1. 

433 J HL = (RSP) + 4. DE = (HL). 


PUSH DE. Go to NEXT1. 
434 2CONSTANT CREATE 


SMUDGE 
HERE 2! Write double number. 
LIT 0004 
ALLOT Reserve four more bytes. 
(;CODE) Link to following code. 
435 INC DE. Exchange DE,HL. 


HL = HL + 2 DE = (HL). 
PUSH DE. HL = HL — 2. 
DE = (HL). PUSH DE. 


Go to NEXT1. 
436 2VARIABLE 2CONSTANT 
(;CODE) Link to following code. 
437 INC DE. PUSH DE. Goto NEXT1. 
438 U.R >ROR> Make 20S double number 
(unsigned) 


D.R 
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439 20VER 





2SWAP 
2DUP 

>R>R 
2SWAP 
R>R> 


Additional pages for 
ADVANCED SPECTRUM FORTH 


Stack:abcdbecomescdab 
Stack:cdabab 

ab toreturn stack. Stackcdabd 
Stack:abcd 

Restore ab 


In early issues, this contained an error, in that the last two words were >R 
instead of R>. To correct the error, locations 7F4E and 7D50 need to be 
changed from 6173 to 6188. 


440 


441 


442 


445 
446 
447 


EXIT 


>R DROP 


Discard TORS. 


This word needs to be used with extreme care. 


PLOT 


X1 

Y1 
INCX 
INCY 
DRAW 


LIT 5C7E C@ 
DUP 0 SWAP 
Y1 2! 

— DUP ABS 


ROT 


LIT 5C7D C@ 
DUP 0 SWAP 


X1 2! 
— DUP ABS 


ROT MAX 


POP HL. POP DE. PUSH BC. 
PUSH IX. C = E.B=L.IfHorD 
is non-zero go to 442. 

If L exceeds AFH go to 442. 
CALL 22DF 

POP IX. POP BC. Go to NEXT1. 
A double variable used by DRAW 
A double variable used by DRAW 
A double variable used by DRAW 
A double variable used by DRAW 
Read LASTY 

Stack: x y LASTY O LASTY 
Store 65536*LASTY in Y1. 
Stack: x y—LASTY 

y—LASTY (abs) x 

Stack: y—LASTY 

y —LASTY (abs) x 

Read LASTX 

Stack: y—LASTY y—LASTY (abs) 
x LASTX 0 LASTX 

Store 65536*LASTX in X1 

Stack: y— LASTY y—LASTY (abs) 
x—LASTX x—LASTX(abs) 
Stack: y—LASTY x—L A4STX 
(greater of absolutes’ 
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448 


449 


450 


491 


452 


*453 CASE 


*454 OF 


>RDUPO< = Stack: y—LASTY x—LASTX flag 

OBRANCH 0012 If x-—LASTX positive go to 448 

ABS 0 SWAP _ Stack: y—LASTY 0 
x—LASTX(abs) 

R M/MOD Divide 65536*(x— LASTX) by 
greater of absolutes. 


DMINUS 


Negate quotient 


BRANCH 000A Go to 449. Stack: y—LASTY 


rem double-quotient. 


O SWAP R Stack: y—LASTY 0 x—LASTX 

M/MOD Divide 65536*x—LASTX by 
greater of absolutes. 

INCX 2! Store quotient in INCX 

DROP Discard remainder 

DUP O< Stack: y—LASTY flag 


OBRANCH 0012 If y—LASTY positive go to 450 
ABS 0 SWAP _ Stack: 0 y—LASTY(abs) 


R M/MOD Divide 65536*(y—LASTY/(abs)) 
by greater of absolutes. 
DMINUS Negate quotient 


BRANCH 000A Go to 451. 


O SWAP R Stack: 0 y—LASTY 

M/MOD Divide 65536*(y—LASTY) by 
greater of absolutes. 

INCY 2! Store quotient in INCY 

DROP Discard remainder 

R>1+0 

(DO) 

X1 @ Read upper half of X1 

Y1@ Read upper half of Y1 

PLOT 

X12@ Read X1 

INCX 2@ Read INCX 

D+ X12! Store double sum in X1 

Y12@ Read Y1 

INCY 2@ Read INCY 

D+ Y1 2! Store double sum in Y1 

(LOOP) FFD8 Loop to 452 

?COMP Error if not compiling 

CSP @ Read SP hold 

ICSP Set SP hold from SP 

LIT 0004 PAIRS reference 

LIT 0004 

?PAIRS Check pairing 


*455 ENDOF 


*456 ENDCASE 


457 


458 
459 INKEY 


460 


461 INIT-DISC 


462 UDG 


COMPILE OVER 


COMPILE = 

COMPILE OBRANCH 

HERE 0, 

COMPILE DROP 

LIT 0005 PAIRS reference 
LIT 0005 

?PAIRS Check pairing 
COMPILE BRANCH 

HERE O, 

SWAP 2 

ENDIF 

LIT 0004 PAIRS reference 
LIT 0004 

?PAIRS Check pairing 
COMPILE DROP 

SP@ Read SP 

CSP @ Read SP hold 

— 0= 


OBRANCH OOOA If SP = SP hold go to 458 
2 ENDIF 


BRANCH FFEC Go to 457 

CSP ! Set SP hold from TOS 
PUSH BC. CALL 028E. C = 0. 
If A #0 go to 460. 


Else call 031E. If no carry go 
to 460. DEC D. E = A. CALL 0333. 


L=A.H=0.POP BC. 


Go to NEXT1. 

LIT DOOO 

LIT FF2B 

BLANKS Clear DOOO — FF2B to 
space codes 


LIT5C7B@  ReadUDG 
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The first number against each word is a link in Appendix A. 


FORTH Vocabulary 
| 77 21,24 
ICSP 146 46 
# 322 42 
#> 320 43 
#BUFF 280 53 
#S 324 42 
302 71 
( 229 650 
(.‘‘) 173 41 
(;CODE) 160 70 
(+LOOP) 13 73 
(ABORT) 205 46 
(DO) 14. 69 
(FIND) 19 — 
(LINE) 258 — 
(LOOP) 9 69 
(NUMBER) 198 — 
(TAPE) 340 49 
* 251 19,20 
*/ 256 19,20 
*/MOD 255 19,20 
+ 63 4,5 
+! 72 21 
+— 241 17,20 
+BUF 281 54 
+LOOP 309 39 
+ORIGIN 100 47 
; 128. — 
— 130. 6—:«*13, 14 
—_—> 301 49 
—DUP 138 39 
—FIND 204 42 
— TRAILING 169 43 
328 9,11 
- 174 41 
~CPU 339 4 
LINE 259 54 


0< 

O= 
OBRANCH 
1+ 

2+ 

2! 

2@ 
2CONSTANT 
2DRCP 
2DUP 
2OVER 
2SWAP 
2VARIABLE 


>] 

,;CODE 
RS 

< 

<# 
<BUILDS 


> 
>R 

? 

2?COMP 
2?CSP 
?ERROR 
2EXEC 
?LOADING 
2?PAIRS 


326 
253 
252 
90 
91 
92 
93 
62 
61 


124 
125 

79 

76 
434 
347 

71 
439 
348 
438 

80 

82 
161 

56 
132 
319 
162 
131 
135 

58 
329 
149 
152 
147 
150 
153 
151 


11,12 
19,20 
19,20 
47 
47 
47 


S883 


17,19 
17,20 
21,24 
21,24 
22 
15 
15,18 
15,16 
15 
22,24 
32,35 
32,36 
70 
7@ 


42 
72 


16 
21,24 


45 


46 


HEX 

HI 

HLD 
HOLD 

| 

\ 

ID. 

IF 
IMMEDIATE 
IN 

INDEX 
INIT—DISC 
INK 
INKEY 
INP 
INTERPRET 
INVERSE 
J 

KEY 
LATEST 
LEAVE 
LFA 
LIMIT 
LINE 
LINK 
LIST 

LIT 
LITERAL 
LO 

LOAD 
LOADT 
LOOP 

Wo 

M/ 
M/MOD 
MAX 
MESSAGE 
MIN 
MINUS 
MOD 
MON 
NEXT 


158 
295 
123 
193 
15 
432 
209 
314 
223 
111 
352 
461 
419 
459 
405 
216 
429 
433 
33 
141 
o7 
142 
97 
343 
337 
334 
3 
213 
294 
300 
344 
308 
249 
250 
257 
247 
260 
245 
65 
254 
341 
402 


11,12 
53 
43 
43 
39 


39 
43 
38 
71 
43 
50 
49 


25 

44 

45 

12 

25 

39 

44 
84,34 
40 
32,34 
53 

54 

3 

59, 49,50 
306,71 

53 

49 

49 

39 
18,19,20 
18,19,26 
17,20 
17,20 

46 

17,20 

14 

19,20 

2 


NEXT 1 
NEXT2 
NFA 
NOOP 
NOT 
NUMBER 
OF 
OFFSET 
OR 

OUT 
OUTP 
OVER 
PAD 
PAPER 
PFA 
PLOT 
POINT 
PREV 
PUSHDE 
PUSHHL 
QUERY 
QUIT 

R 

R# 

R/W 

R> 

RO 
REPEAT 
ROT 
RP@ 
RP! 
S—>D 
SO 
SAVET 
SCR 
SCREEN 
SIGN 
SIZE 
SMUDGE 
SP! 
SP@ 
SPACE 


144 

83 
431 
201 
454 
114 

50 
112 
406 

67 
194 
413 
145 
441 
418 
279 


1404 
2403 


184 
230 

60 
122 
296 

09 
102 
313 
136 

54 

55 
240 
101 
345 
112 
407 
321 
349 
157 

93 

92 
137 


32,34 
47 


41 


16,19 
42 
45 
15,16 
31 
25 
32,34 
26 


i 2S 


59 ,53,40 
16 
91 
95 
16 
46 
40 
15 
46 
46 
14 
46 
49 


25 
42 
47 
33,34 
46 
46 
16 


2STACK 


215 46 D+-— 242 17,20 
2? TERMINAL 34 38 D. 327 10,11 
@ 74 21,24 D.R 325 11,12 
ABORT 233 40 DABS 244 17,20 
ABS 243 = 17,20 DECIMAL 159 11,12 
AGAIN 312 39 DEFINITIONS 228 50 
ALLOT 127 22,24 DIGIT 16 44 
AND 49 16,19 DLITERAL 214 71 
AT 408 25 DMINUS 66 14 
ATTR 417 25 DO 307 39 
B/BUF 98 53 DOES> 163 72 
B/SCR 99 53 DP 108 — 
BACK 303 69 DPL 119 10,43,44 
BASE 118 11,12 DRAW 447 26 
BEGIN 304 39 DRO 286 54 
BL 94 — DROP 68 15 
BLANKS 129 24,25 DUP 70 14 
BLEEP 412 26 EDITOR 358 45,49 
BLK 110 53 ELSE 315 38 
BLOCK 290 54 EMIT 32 42 
BRANCH 7 37 EMPTY BUFFERS 284 54 
BRIGHT 425 25 ENCLOSE 28. — 
BORDER 409 25 END 311 40 
BUFFER 287 54 ENDCASE 456 41 
C! 78 21,24 ENDIF 305 39 
C/L 95 53 ENDOF 455 41 
C, 129 70 ERASE 191 24,25 
C@ 78 21,24 ERROR 206 45 
CASE 453 41 EXECUTE 6 47 
CFA 143 32,34 EXIT 440 40 
CLS 338 16 EXPECT 176 44 
CMOVE 36 24,25 FENCE 107 45,75 
COLD 239 47 FILL 188 23,25 
COMPILE 154 47 FIRST 96 53 
CONSTANT 84 22,24 FLASH 423 25 
CONTEXT 115 45 FLD 1200 — 
COUNT 165 43 FLUSH 298 54 
CR 35 16 FORGET 351 34,45 
CREATE 210 70 FORTH 996 45 
CSP 121 46 FREE 350 3,46 
CURRENT 116 70 GOVER 427 25 
D+ 64 14 HERE 126 46 


SPACES 317 16 
STATE 117 45 
SWAP 69 15,17 
TEXT 342 55 
THEN 306 39 
TIB 103 13 
TOGGLE 73 24.25.34 
TRAVERSE 139 32,34 
TRIAD 355 50 
TYPE 166 43 
U< 133 38 
U* 38 13,14 
U. 330 10,11 
U.R 438 11,12 
U/MOD 42 13,14 
UDG 462 26 
UNTIL 310 -40 
UPDATE 283 55 
EDITOR Vocabulary 
#LAG 363 52 
#LEAD 362 52 
#LOCATE 361 52 
—MOVE 364 52 
—TEXT 382 52 
1LINE 390 52 
B 398 51 

C 401 51 
CLEAR 378 «51 
COPY 380 51 

D 369 51 
DELETE 394 52 

E 366 51 

F 396 51 


USE 
USER 
VARIABLE 
VERIFY 
VLIST 
VOC-LINK 
VOCABULARY 
WARM 
WARNING 
WHERE 
WHILE 
WIDTH 
WORD 

X 

XOR 


[ 
[COMPILE} 


] 


278 
88 
86 

346 

331 

109 

224 

236 

106 

360 

316 

105 

195 

185 
31 

155 

212 

156 


391 
365 
376 
373 
371 
387 
395 
375 
374 
367 
372 
372 
377 
399 


04 
47 
21,24 
49 
33,50 


74 
47 
46,50 
46 
40 
71 
41 
71 
20,18 
70 
71 
78 


52 
a1 
31 
51 
o1 
52 
51 
51 
o1 
31 
31 
51 
51 
o1 


ADVANCED SPECTRUM FORTH 
MELBOURNE HOUSE REGISTRATION CARD 


Please fill out this page and return it promptly in order that we may keep 
you informed of new software and special offers that arise. Simply fill in 
and indicate the correct address on the reverse side. 


Name .... ccc ccc cc ccc eee eee eee eben ee eee eee e eee enenas 


Which computer do you OWN? ......... 00... eee eens 
Where did you learn of this product? 

[] Magazine. If so, which one? ........... 000. cece ec e eee eee eee 
[] Through a friend 

LC) Saw it in a Retail Shop 

(] Other. Please specify ......00. 00... ccc cece cece eee tenes 
Which magazines do you purchase? 

Regularly: 2... 0.0... ccc cece eee eee eee teen eens wees 
Occasionally: ....... 0.0... cc ccc cece ence cent e nee ee es 
What Age are you? 


CJ 10-15 [] 16-19 [] 20-24 [] Over 25 
We are continually writing new material and would appreciate receiving 
your comments on our product. 


How would you rate this software? 


C] Excellent C] Value for money 
[1 Good C] Priced right 
[_] Poor LJ Overpriced 


Please tell us what books/software you would like to see produced for 
your SPECTRUM. 








ADVANCED SPECTRUM FORTH is an essential aid to anyone who wishes to discover FORTH’s 
true potential on their Spectrum, providing the bridge from beginner status to advanced 
FORTH programmer, using examples and detailed explanations. 


The popularity of FORTH as an alternative language, combining the ease of a high level 
language and the speed of machine code, has led to it being available to the Spectrum 
user. 


However, to really utilise the power and flexibility of FORTH, a lot more in-depth knowledge 
of the language is required than just knowing and being able to use the pre-defined FORTH 
words. 


This book is designed to provide details and to illustrate the techniques that will allow the 
FORTH programmer, who is already familiar with FORTH, to realise the full potential of 
FORTH as a language. 


Apart from an in-depth look at Abersoft’s FIG-FORTH this book deals with specific 
programming techniques and FORTH program design considerations, using examples. 


This book contains sections which provide a close look at how FORTH handles arithmetic, 
how to manipulate strings and arrays, how to define new dictionary definitions, and a 
chapter which covers the peculiarities of FORTH on the Spectrum. 


Aimed specifically at those programmers who know the essentials of FORTH and dealing 
exclusively with Abersoft FORTH for the Spectrum, this book provides those details about 
the Spectrum and about Abersoft FORTH that more general books cannot provide. 


Melbourne 
House 
Publishers 
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